Definition of a general enum.Enum-derived enum type in Python. More...

#include <enum_definition.h>

Inheritance diagram for lass::python::EnumDefinition< EnumType, ValueType >:

[legend]

Collaboration diagram for lass::python::EnumDefinition< EnumType, ValueType >:

Data Structures
struct	Enumerator
	Represents a single enumerator with name, C++ enum value, and Python value. More...

Public Member Functions
	EnumDefinition (const char *name)
	Construct with enum name only.

	EnumDefinition (const char name, const char doc)
	Construct with name and documentation.

	EnumDefinition (const char *name, std::initializer_list< Enumerator > enumerators)
	Construct with name and enumerators list.

	EnumDefinition (const char name, const char doc, std::initializer_list< Enumerator > enumerators)
	Construct with name, documentation, and enumerators list.

void	addEnumerator (std::string name, TEnum enumerator, TValue value)
	Add an enumerator to the definition.

PyObject *	build (TEnum value) const
	Creates a Python enum instance from a C++ enum value.

int	get (PyObject *obj, TEnum &value) const
	Extracts a C++ enum value from a Python object.

const char *	name () const
	The name of the Python enum type.

const char *	doc () const
	Optional docstring for the Python enum type.

PyObject *	type () const
	The Python enum type object, after freezeDefinition() has been called.

PyObject *	freezeDefinition (const char moduleName, const char scopeName)
	Freeze the enum definition and create the Python enum type.

Protected Member Functions
TPyObjPtr	freezeEnumerators ()
	Converts stored enumerators to Python tuple format and builds lookup tables.

TPyObjPtr	doFreezeDefinition (TPyObjPtr &&kwargs) override
	Creates a generic `enum.Enum`-derived type.

TPyObjPtr	valueObject (PyObject *obj) const
	Returns the value of an enum instances as a Python object.

Detailed Description

template<typename EnumType, typename ValueType>
class lass::python::EnumDefinition< EnumType, ValueType >

Definition of a general enum.Enum-derived enum type in Python.

This creates enums with custom value types (not just integers or strings). This is the base class for StrEnumDefinition and can be used directly for advanced enum types with custom value types.

This class is typically not used directly. Use PY_SHADOW_ENUM and PY_DECLARE_ENUM_* macros instead.

Usage Example:: // In header:

PY_SHADOW_ENUM(LASS_DLL_EXPORT, MyEnum, std::string);

// In source:

PY_DECLARE_ENUM_EX(MyEnum, std::string)("MyEnum", "MyEnum documentation", {

{ "VALUE1", MyEnum::Value1, "custom_value_1" },

{ "VALUE2", MyEnum::Value2, "custom_value_2" },

});

// Add to module or class:

PY_MODULE_ENUM(mymodule, MyEnum); // or PY_CLASS_ENUM(MyClass, MyEnum);

PY_SHADOW_ENUM
#define PY_SHADOW_ENUM(dllInterface, t_cppEnum, t_valueType)
Specializes PyExportTraits for a C++ enum using generic enum.Enum.
Definition enum_definition.h:975

PY_MODULE_ENUM
#define PY_MODULE_ENUM(i_module, t_cppEnum)
Adds an enum definition to a Python module.
Definition enum_definition.h:1117

PY_DECLARE_ENUM_EX
#define PY_DECLARE_ENUM_EX(t_cppEnum, t_valueType)
Defines the enumDefinition for initialization with constructor arguments for generic enum....
Definition enum_definition.h:1021

See also: PY_SHADOW_ENUM; PY_DECLARE_ENUM_NAME; PY_DECLARE_ENUM_NAME_DOC; PY_DECLARE_ENUM_EX; PY_MODULE_ENUM; PY_CLASS_ENUM

Definition at line 579 of file enum_definition.h.

Constructor & Destructor Documentation

◆ EnumDefinition() [1/4]

template<typename EnumType, typename ValueType>

lass::python::EnumDefinition< EnumType, ValueType >::EnumDefinition ( const char * name )

inline

Construct with enum name only.

Parameters

name	Python class name for the enum type (must have static storage duration)

Definition at line 596 of file enum_definition.h.

References lass::python::EnumDefinitionBase::EnumDefinitionBase(), and lass::python::EnumDefinitionBase::name().

◆ EnumDefinition() [2/4]

template<typename EnumType, typename ValueType>

lass::python::EnumDefinition< EnumType, ValueType >::EnumDefinition	(	const char *	name,
		const char *	doc )

inline

Construct with name and documentation.

Parameters

name	Python class name for the enum type (must have static storage duration)
doc	Optional docstring for the Python enum type (must have static storage duration, or nullptr)

Definition at line 605 of file enum_definition.h.

References lass::python::EnumDefinitionBase::doc(), lass::python::EnumDefinitionBase::EnumDefinitionBase(), and lass::python::EnumDefinitionBase::name().

◆ EnumDefinition() [3/4]

template<typename EnumType, typename ValueType>

lass::python::EnumDefinition< EnumType, ValueType >::EnumDefinition	(	const char *	name,
		std::initializer_list< Enumerator >	enumerators )

inline

Construct with name and enumerators list.

Parameters

name	Python class name for the enum type (must have static storage duration)
enumerators	List of name-enum-value triples defining the enum members

Definition at line 614 of file enum_definition.h.

References lass::python::EnumDefinitionBase::EnumDefinitionBase(), and lass::python::EnumDefinitionBase::name().

◆ EnumDefinition() [4/4]

template<typename EnumType, typename ValueType>

lass::python::EnumDefinition< EnumType, ValueType >::EnumDefinition	(	const char *	name,
		const char *	doc,
		std::initializer_list< Enumerator >	enumerators )

inline

Construct with name, documentation, and enumerators list.

Parameters

name	Python class name for the enum type (must have static storage duration)
doc	Optional docstring for the Python enum type (must have static storage duration, or nullptr)
enumerators	List of name-enum-value triples defining the enum members

Definition at line 625 of file enum_definition.h.

References lass::python::EnumDefinitionBase::doc(), lass::python::EnumDefinitionBase::EnumDefinitionBase(), and lass::python::EnumDefinitionBase::name().

Member Function Documentation

◆ addEnumerator()

template<typename EnumType, typename ValueType>

void lass::python::EnumDefinition< EnumType, ValueType >::addEnumerator	(	std::string	name,
		TEnum	enumerator,
		TValue	value )

inline

Add an enumerator to the definition.

Parameters

name	Python name for the enumerator
enumerator	C++ enum value
value	Python value for the enumerator

Definition at line 636 of file enum_definition.h.

References lass::python::EnumDefinitionBase::name().

◆ build()

template<typename EnumType, typename ValueType>

PyObject * lass::python::EnumDefinition< EnumType, ValueType >::build ( TEnum value ) const

inline

Creates a Python enum instance from a C++ enum value.

Looks up the Python value corresponding to the C++ enum and creates an enum instance.

Definition at line 644 of file enum_definition.h.

References lass::python::EnumDefinitionBase::type().

◆ get()

template<typename EnumType, typename ValueType>

int lass::python::EnumDefinition< EnumType, ValueType >::get	(	PyObject *	obj,
		TEnum &	value ) const

inline

Extracts a C++ enum value from a Python object.

Accepts enum instances and compatible value types. Returns 0 on success, 1 on failure.

Definition at line 661 of file enum_definition.h.

References lass::python::EnumDefinitionBase::type(), and lass::python::EnumDefinitionBase::valueObject().

◆ freezeEnumerators()

template<typename EnumType, typename ValueType>

TPyObjPtr lass::python::EnumDefinition< EnumType, ValueType >::freezeEnumerators ( )

inlineprotected

Converts stored enumerators to Python tuple format and builds lookup tables.

Creates bidirectional mappings between C++ enum values and Python values.

Definition at line 711 of file enum_definition.h.

References lass::python::EnumDefinition< EnumType, ValueType >::Enumerator::enumerator, lass::python::fromSharedPtrToNakedCast(), lass::python::EnumDefinition< EnumType, ValueType >::Enumerator::name, and lass::python::EnumDefinition< EnumType, ValueType >::Enumerator::value.

Referenced by doFreezeDefinition().

◆ doFreezeDefinition()

template<typename EnumType, typename ValueType>

TPyObjPtr lass::python::EnumDefinition< EnumType, ValueType >::doFreezeDefinition ( TPyObjPtr && kwargs )

inlineoverrideprotectedvirtual

Creates a generic enum.Enum-derived type.

Processes enumerators and creates a Python enum type with custom value types.

Implements lass::python::EnumDefinitionBase.

Reimplemented in lass::python::StrEnumDefinition< EnumType, ValueType >.

Definition at line 731 of file enum_definition.h.

References freezeEnumerators(), lass::python::impl::makeEnumType(), and lass::python::EnumDefinitionBase::name().

◆ freezeDefinition()

PyObject * lass::python::EnumDefinitionBase::freezeDefinition	(	const char *	moduleName,
		const char *	scopeName )

inherited

Freeze the enum definition and create the Python enum type.

Note: This method should not be called directly. Instead, use PY_MODULE_ENUM() or PY_CLASS_ENUM() to add the enum to a module or class, which will call this method at the appropriate time.

Definition at line 247 of file enum_definition.cpp.

◆ valueObject()

TPyObjPtr lass::python::EnumDefinitionBase::valueObject ( PyObject * obj ) const

protectedinherited

Returns the value of an enum instances as a Python object.

If the object is not an instance of this enum type, a Python exception will be set and a null pointer will be returned.

Definition at line 230 of file enum_definition.cpp.

Referenced by lass::python::EnumDefinition< EnumType, ValueType >::get(), and lass::python::IntEnumDefinition< EnumType >::get().

The documentation for this class was generated from the following file:

enum_definition.h

Data Structures

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ EnumDefinition() [1/4]

◆ EnumDefinition() [2/4]

◆ EnumDefinition() [3/4]

◆ EnumDefinition() [4/4]

Member Function Documentation

◆ addEnumerator()

◆ build()

◆ get()

◆ freezeEnumerators()

◆ doFreezeDefinition()

◆ freezeDefinition()

◆ valueObject()