Class Definitions

Detailed Description

Defining Python classes from C++ with methods, properties, operators, and nested types.

This module provides the internal machinery used by the class export macros to define Python classes backed by C++ types. A class definition aggregates constructors, methods (including Python special methods/operators), properties, static members, nested classes and enums, and then materializes a Python type when frozen.

Class Components

A Python class can contain:

• Constructors: Multiple overloads via __new__ dispatchers
• Methods: Regular instance methods with overload support
• Free Methods: Functions that operate on the instance but are not members
• Static Methods: Class-level methods accessible without instances
• Operators: Python special methods (__add__, __eq__, etc.)
• Properties: Getter/setter pairs for attribute access
• Public Members: Direct access to public member variables
• Static Constants: Class-level constant values
• Nested Classes: Inner classes defined within the outer class
• Nested Enums: Enum types scoped to the class

Usage Overview

To export a C++ class to Python, you typically use macros that work on a Python class. Macro names follow a consistent grammar, see Python Macro Name Conventions.

// Define class in header
class MyClass: public PyObjectPlus
{
    PY_HEADER(PyObjectPlus)
public:
    MyClass();
    MyClass(int value);
    MyClass(const std::string& name, double factor);
    
    void process();
    void process(int iterations);                    // Overload #1 (member)
    int calculate(int input) const;
    std::string getName() const;
    void setName(const std::string& name);
    static int getGlobalCount();
    std::string toString() const;                    // For __str__
    
    int publicValue;
    static const int MAX_SIZE = 100;
};
 
// Free functions for export as methods
void reset(MyClass* obj);
void process(MyClass* obj, const std::string& mode); // Overload #2 (free function)
double computeScore(const MyClass& obj, double multiplier);
MyClass combine(const MyClass& a, const MyClass& b);
 
// Special method implementations
bool operator==(const MyClass& a, const MyClass& b);
bool operator<(const MyClass& a, const MyClass& b);
MyClass operator+(const MyClass& a, const MyClass& b);
MyClass operator-(const MyClass& a, const MyClass& b);
std::string repr(const MyClass& obj);                // For __repr__
size_t hash(const MyClass& obj);                     // For __hash__
 
// Register class methods and properties in source
PY_DECLARE_CLASS_NAME_DOC(MyClass, "MyClass", "Demonstration class with various binding types")
 
// Multiple constructor overloads
PY_CLASS_CONSTRUCTOR_0(MyClass)
PY_CLASS_CONSTRUCTOR_1(MyClass, int)
PY_CLASS_CONSTRUCTOR_2(MyClass, const std::string&, double)
 
// Mixed overloading: regular methods + free functions for same Python method
PY_CLASS_METHOD(MyClass, process)                           // void process()
PY_CLASS_METHOD_1(MyClass, process, int)                    // void process(int)
PY_CLASS_FREE_METHOD_NAME(MyClass, process, "process")      // void process(MyClass*, const std::string&)
 
// Other regular methods
PY_CLASS_METHOD_DOC(MyClass, calculate, "Calculate result from input value")
PY_CLASS_STATIC_METHOD(MyClass, getGlobalCount)
 
// Properties (getter/setter pairs)
PY_CLASS_MEMBER_RW_DOC(MyClass, name, getName, setName, "Object name property")
 
// Public member access
PY_CLASS_MEMBER_R(MyClass, publicValue)
 
// Free functions as methods (various forms)
PY_CLASS_FREE_METHOD(MyClass, reset)
PY_CLASS_FREE_METHOD_NAME_DOC(MyClass, computeScore, "compute_score", "Calculate score with multiplier")
PY_CLASS_FREE_METHOD_DOC(MyClass, combine, "Combine two objects")
 
// Python special methods via member and free functions
PY_CLASS_METHOD_NAME(MyClass, toString, methods::_str_)          // Member function for __str__
PY_CLASS_FREE_METHOD_NAME(MyClass, repr, methods::_repr_)       // Free function for __repr__
PY_CLASS_FREE_METHOD_NAME(MyClass, hash, methods::_hash_)       // Free function for __hash__
 
// Comparison and arithmetic operators
PY_CLASS_FREE_METHOD_NAME(MyClass, operator==, methods::_eq_)
PY_CLASS_FREE_METHOD_NAME(MyClass, operator<, methods::_lt_)
PY_CLASS_FREE_METHOD_NAME(MyClass, operator+, methods::_add_)
PY_CLASS_FREE_METHOD_NAME(MyClass, operator-, methods::_sub_)
 
// Static constants and values
PY_CLASS_STATIC_CONST(MyClass, "MAX_SIZE", MyClass::MAX_SIZE)
PY_CLASS_STATIC_CONST(MyClass, "VERSION", "1.2.3")
 
// Add to module
PY_MODULE_CLASS(mymodule, MyClass)

Topics
	Class Attribute Export Macros
	Export values and nested types as attributes on the Python class itself.
	Method Export Macros
	These macros export C++ methods on a class to Python.
	Casting Method Export Macros (Deprecated)
	Static Method Export Macros
	Export C++ static methods or free functions as Python static methods.
	Data Member Export Macros
	Export C++ class data members as Python properties.
	Constructor Export Macros
	Export C++ constructors directly as Python class constructors.

Classes
class	lass::python::impl::ClassDefinition
	Definition of a Python class. More...

Class Declaration & Setup
Macros to declare and configure Python classes from C++ types. These macros create the internal class definition objects that aggregate all the information needed to generate a Python type. Every C++ class that needs to be exposed to Python must be declared using one of these macros. LASS supports two approaches for exporting C++ classes to Python: Direct Python classes: C++ classes that directly inherit from lass::python::PyObjectPlus and are designed to be Python-aware from the start. Python Shadow Classes: Wrapper classes created for existing native C++ types using the shadow system. Note In both cases, the class parameter in these declaration macros refers to the Python binding class (either PyObjectPlus-derived or shadow wrapper), never the underlying native C++ type being shadowed. The basic form is PY_DECLARE_CLASS( i_cppClass ) with: i_cppClass : Python binding class, either a shadow class or a class deriving from lass::python::PyObjectPlus Common suffixes The _NAME and _DOC suffixes allow you to specify a custom Python name and docstring. Macro Fixed parameters Adds parameters Use for ... PY_DECLARE_CLASS_NAME t_cppClass s_name Custom Python name PY_DECLARE_CLASS_DOC i_cppClass s_doc With docstring PY_DECLARE_CLASS_NAME_DOC t_cppClass s_name, s_doc Custom Python name + Docstring PY_DECLARE_CLASS_EX t_cppClass s_name, i_uniqueClassIdentifier (deprecated) Direct Python Class Example: // In header file (MyClass.h): class MyClass: public PyObjectPlus { PY_HEADER(PyObjectPlus) public: MyClass(); void someMethod(); }; // In source file (MyClass.cpp): PY_DECLARE_CLASS_NAME_DOC(MyClass, "MyClass", "A sample class") // ... add methods, constructors, properties etc. Shadow Class Example: // Existing non-Python-aware C++ class: class LegacyClass { public: void doSomething(); }; // Shadow wrapper class: PY_SHADOW_CLASS(LASS_DLL_EXPORT, PyShadowLegacyClass, LegacyClass) // Declaration (note: we declare the shadow class, not LegacyClass): PY_DECLARE_CLASS_NAME_DOC(PyShadowLegacyClass, "LegacyClass", "Legacy class wrapper")
#define	PY_DECLARE_CLASS_NAME_DOC(t_cppClass, s_name, s_doc)
	Declare a Python class with full control over name and documentation.
#define	PY_DECLARE_CLASS_NAME(t_cppClass, s_name)
	Declare a Python class with custom name but no documentation.
#define	PY_DECLARE_CLASS_DOC(i_cppClass, s_doc)
	Declare a Python class with automatic name and custom documentation.
#define	PY_DECLARE_CLASS(i_cppClass)
	Declare a Python class with automatic name and no documentation.
#define	PY_DECLARE_CLASS_EX(t_cppClass, s_name, i_uniqueClassIdentifier)
	Legacy class declaration macro.

Macro Definition Documentation

PY_DECLARE_CLASS_NAME_DOC

#define PY_DECLARE_CLASS_NAME_DOC	(		t_cppClass,
			s_name,
			s_doc )

Declare a Python class with full control over name and documentation.

This is the primary class declaration macro that creates the internal ClassDefinition object for a C++ class. All other class declaration macros ultimately call this one. The class definition collects constructors, methods, properties, and other elements that will be added later using PY_CLASS_* macros.

Parameters

t_cppClass	Python binding class type. This must be either: A class directly inheriting from PyObjectPlus, or A shadow class created with PY_SHADOW_CLASS macros. Never pass the underlying native C++ shadowed type.
s_name	Python class name as string literal
s_doc	Class documentation string (or nullptr for no doc)

Note

This macro must be used exactly once per class and only in source files, never in headers!

Direct Python Class Example:

PY_DECLARE_CLASS_NAME_DOC(MyClass, "MyClass", "A sample direct Python class")

Shadow Class Example:

PY_DECLARE_CLASS_NAME_DOC(PyShadowLegacy, "LegacyClass", "Wrapper for LegacyClass")

Definition at line 3834 of file pyobject_macros.h.

PY_DECLARE_CLASS_NAME

#define PY_DECLARE_CLASS_NAME	(		t_cppClass,
			s_name )

Value:

    PY_DECLARE_CLASS_NAME_DOC( t_cppClass, s_name, 0 )

Declare a Python class with custom name but no documentation.

Convenience wrapper around PY_DECLARE_CLASS_NAME_DOC that omits the documentation string. Use this when you want to control the Python class name but don't need documentation.

Parameters

t_cppClass	Python binding class type (PyObjectPlus-derived or shadow class)
s_name	Python class name as string literal

Example

PY_DECLARE_CLASS_NAME(MyClass, "MyClass")

Definition at line 3856 of file pyobject_macros.h.

PY_DECLARE_CLASS_DOC

#define PY_DECLARE_CLASS_DOC	(		i_cppClass,
			s_doc )

Value:

    PY_DECLARE_CLASS_NAME_DOC( i_cppClass, LASS_STRINGIFY(i_cppClass), s_doc )

Declare a Python class with automatic name and custom documentation.

Convenience wrapper that uses the C++ class name as the Python class name but allows custom documentation. The class name is automatically stringified.

Parameters

i_cppClass	Python-exportable C++ class identifier (unqualified name)
s_doc	Class documentation string

Example

PY_DECLARE_CLASS_DOC(MyClass, "A sample class for demonstration") // Creates Python class named "MyClass"

Definition at line 3874 of file pyobject_macros.h.

PY_DECLARE_CLASS

#define PY_DECLARE_CLASS

(

i_cppClass

)

Value:

    PY_DECLARE_CLASS_NAME_DOC( i_cppClass, LASS_STRINGIFY(i_cppClass), 0 )

Declare a Python class with automatic name and no documentation.

The simplest class declaration macro. Uses the C++ class name as the Python class name and provides no documentation string. Most commonly used for basic class exports.

Parameters

i_cppClass

Python binding class identifier (unqualified name)

Example

PY_DECLARE_CLASS(MyClass) // Creates Python class named "MyClass" with no documentation

Definition at line 3891 of file pyobject_macros.h.

PY_DECLARE_CLASS_EX

#define PY_DECLARE_CLASS_EX	(		t_cppClass,
			s_name,
			i_uniqueClassIdentifier )

Value:

    PY_DECLARE_CLASS_NAME_DOC( t_cppClass, s_name, 0 )

Legacy class declaration macro.

Parameters

t_cppClass	Python binding class type
s_name	Python class name
i_uniqueClassIdentifier	Unused parameter (legacy)

Deprecated

This macro is deprecated and should not be used in new code. Use PY_DECLARE_CLASS_NAME_DOC() instead.

Definition at line 3905 of file pyobject_macros.h.