Definition of an enum.IntEnum-derived enum type in Python. More...

#include <enum_definition.h>

Inheritance diagram for lass::python::IntEnumDefinition< EnumType >:

[legend]

Collaboration diagram for lass::python::IntEnumDefinition< EnumType >:

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

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

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

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

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

void	addEnumerator (std::string name, TEnum value)
	Add an enumerator member 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	doFreezeDefinition (TPyObjPtr &&kwargs) override
	Creates an `enum.IntEnum`-derived type.

TPyObjPtr	doValueObject (PyObject *obj) const override
	Extracts integer values from enum instances or integer objects.

virtual TPyObjPtr	doMakeEnumType (TPyObjPtr &&enumerators, TPyObjPtr &&kwargs)
	Creates the actual `enum.IntEnum` type object.

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

Detailed Description

template<typename EnumType>
class lass::python::IntEnumDefinition< EnumType >

Definition of an enum.IntEnum-derived enum type in Python.

C++ enums exported using IntEnumDefinition will generate a new enum type derived from enum.IntEnum. The values of the Python enum will map directly on the C++ enum values, but then names need to be defined at export.

As enum.IntEnum is used, the Python enum instances will also be valid int instances, and int instances are accepted when converting from Python to C++.

Because this defines a new type, it must be added to a module or other class.

This class is typically not used directly. Use PY_SHADOW_INT_ENUM and PY_DECLARE_INT_ENUM_* macros instead.

Usage Example:: // In header:

PY_SHADOW_INT_ENUM(LASS_DLL_EXPORT, MyEnum);

// In source:

PY_DECLARE_INT_ENUM_EX(MyEnum)("MyEnum", "MyEnum documentation", {

{ "VALUE1", MyEnum::Value1 },

{ "VALUE2", MyEnum::Value2 },

});

// Add to module or class:

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

PY_DECLARE_INT_ENUM_EX
#define PY_DECLARE_INT_ENUM_EX(t_cppEnum)
Defines the enumDefinition for initialization with constructor arguments for enum....
Definition enum_definition.h:889

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_SHADOW_INT_ENUM
#define PY_SHADOW_INT_ENUM(dllInterface, t_cppEnum)
Specializes PyExportTraits for a C++ enum using enum.IntEnum.
Definition enum_definition.h:846

See also: PY_SHADOW_INT_ENUM; PY_DECLARE_INT_ENUM_NAME; PY_DECLARE_INT_ENUM_NAME_DOC; PY_DECLARE_INT_ENUM_EX; PY_MODULE_ENUM; PY_CLASS_ENUM

Definition at line 312 of file enum_definition.h.

Constructor & Destructor Documentation

◆ IntEnumDefinition() [1/4]

template<typename EnumType>

lass::python::IntEnumDefinition< EnumType >::IntEnumDefinition ( 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 328 of file enum_definition.h.

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

Referenced by lass::python::IntFlagDefinition< EnumType >::IntFlagDefinition().

◆ IntEnumDefinition() [2/4]

template<typename EnumType>

lass::python::IntEnumDefinition< EnumType >::IntEnumDefinition	(	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 337 of file enum_definition.h.

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

◆ IntEnumDefinition() [3/4]

template<typename EnumType>

lass::python::IntEnumDefinition< EnumType >::IntEnumDefinition	(	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-value pairs defining the enum members

Definition at line 346 of file enum_definition.h.

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

◆ IntEnumDefinition() [4/4]

template<typename EnumType>

lass::python::IntEnumDefinition< EnumType >::IntEnumDefinition	(	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-value pairs defining the enum members

Definition at line 357 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>

void lass::python::IntEnumDefinition< EnumType >::addEnumerator	(	std::string	name,
		TEnum	value )

inline

Add an enumerator member to the definition.

Parameters

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

Definition at line 367 of file enum_definition.h.

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

◆ build()

template<typename EnumType>

PyObject * lass::python::IntEnumDefinition< EnumType >::build ( TEnum value ) const

inline

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

Converts the C++ enum to its corresponding Python enum instance.

Definition at line 375 of file enum_definition.h.

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

◆ get()

template<typename EnumType>

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

inline

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

Accepts both enum instances and raw integers. Returns 0 on success, 1 on failure.

Definition at line 385 of file enum_definition.h.

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

◆ doFreezeDefinition()

template<typename EnumType>

TPyObjPtr lass::python::IntEnumDefinition< EnumType >::doFreezeDefinition ( TPyObjPtr && kwargs )

inlineoverrideprotectedvirtual

Creates an enum.IntEnum-derived type.

Converts enumerators to Python tuple format and creates the integer enum type.

Implements lass::python::EnumDefinitionBase.

Definition at line 407 of file enum_definition.h.

References doMakeEnumType(), lass::python::IntEnumDefinition< EnumType >::Enumerator::enumerator, lass::python::fromSharedPtrToNakedCast(), and lass::python::IntEnumDefinition< EnumType >::Enumerator::name.

◆ doValueObject()

template<typename EnumType>

TPyObjPtr lass::python::IntEnumDefinition< EnumType >::doValueObject ( PyObject * obj ) const

inlineoverrideprotectedvirtual

Extracts integer values from enum instances or integer objects.

Handles both integer enum instances and raw Python integers.

Reimplemented from lass::python::EnumDefinitionBase.

Definition at line 431 of file enum_definition.h.

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

◆ doMakeEnumType()

template<typename EnumType>

virtual TPyObjPtr lass::python::IntEnumDefinition< EnumType >::doMakeEnumType	(	TPyObjPtr &&	enumerators,
		TPyObjPtr &&	kwargs )

inlineprotectedvirtual

Creates the actual enum.IntEnum type object.

Can be overridden by derived classes to create different enum types (e.g., IntFlag).

Reimplemented in lass::python::IntFlagDefinition< EnumType >.

Definition at line 456 of file enum_definition.h.

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

Referenced by doFreezeDefinition().

◆ 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

◆ IntEnumDefinition() [1/4]

◆ IntEnumDefinition() [2/4]

◆ IntEnumDefinition() [3/4]

◆ IntEnumDefinition() [4/4]

Member Function Documentation

◆ addEnumerator()

◆ build()

◆ get()

◆ doFreezeDefinition()

◆ doValueObject()

◆ doMakeEnumType()

◆ freezeDefinition()

◆ valueObject()