lass::python::StrEnumDefinition< EnumType, ValueType > Class Template Reference

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

#include <enum_definition.h>

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

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

Public Member Functions
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	doFreezeDefinition (TPyObjPtr &&kwargs) override
	Creates an enum.StrEnum-derived type.
TPyObjPtr	doValueObject (PyObject *obj) const override
	Extracts string values from enum instances or string objects.
TPyObjPtr	freezeEnumerators ()
	Converts stored enumerators to Python tuple format and builds lookup tables.
TPyObjPtr	valueObject (PyObject *obj) const
	Returns the value of an enum instances as a Python object.

Detailed Description

template<typename EnumType, typename ValueType = std::string>
class lass::python::StrEnumDefinition< EnumType, ValueType >

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

C++ enums exported using StrEnumDefinition will generate a new enum type derived from enum.StrEnum (or enum.Enum + str for Python < 3.11). The values of the Python enum will be strings, and how they map on the C++ enum values needs to be defined at export.

As enum.StrEnum is used, the Python enum instances will also be valid str instances, and str 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_STR_ENUM and PY_DECLARE_STR_ENUM_* macros instead.

Usage Example:

// In header:
PY_SHADOW_STR_ENUM(LASS_DLL_EXPORT, Shape);
 
// In source:
PY_DECLARE_STR_ENUM_EX(Shape)("Shape", "Shape documentation", {
    { "CIRCLE", Shape::Circle, "circle" },
    { "SQUARE", Shape::Square, "square" },
});
 
// Add to module or class:
PY_MODULE_ENUM(mymodule, Shape);   // or PY_CLASS_ENUM(MyClass, Shape);

See also

PY_SHADOW_STR_ENUM

PY_DECLARE_STR_ENUM_NAME

PY_DECLARE_STR_ENUM_NAME_DOC

PY_DECLARE_STR_ENUM_EX

PY_MODULE_ENUM

PY_CLASS_ENUM

Definition at line 788 of file enum_definition.h.

Member Function Documentation

doFreezeDefinition()

template<typename EnumType, typename ValueType = std::string>

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

inlineoverrideprotectedvirtual

Creates an enum.StrEnum-derived type.

Processes enumerators and creates a Python string enum type.

Reimplemented from lass::python::EnumDefinition< EnumType, std::string >.

Definition at line 797 of file enum_definition.h.

References lass::python::EnumDefinition< EnumType, std::string >::freezeEnumerators(), lass::python::impl::makeStrEnumType(), and lass::python::EnumDefinition< EnumType, std::string >::name().

doValueObject()

template<typename EnumType, typename ValueType = std::string>

TPyObjPtr lass::python::StrEnumDefinition< EnumType, ValueType >::doValueObject ( PyObject * obj ) const

inlineoverrideprotectedvirtual

Extracts string values from enum instances or string objects.

Handles both string enum instances and raw Python strings.

Reimplemented from lass::python::EnumDefinitionBase.

Definition at line 805 of file enum_definition.h.

References lass::python::EnumDefinition< EnumType, std::string >::type().

addEnumerator()

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

inlineinherited

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.

build()

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

inlineinherited

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.

get()

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

inlineinherited

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.

freezeEnumerators()

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

inlineprotectedinherited

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.

Referenced by lass::python::StrEnumDefinition< EnumType, ValueType >::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 234 of file enum_definition.cpp.

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

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 253 of file enum_definition.cpp.

---

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

• enum_definition.h