lass::python::IntFlagDefinition< EnumType > Class Template Reference

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

#include <enum_definition.h>

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

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

Public Member Functions
	IntFlagDefinition (const char *name, const char *doc, FlagBoundary boundary, std::initializer_list< Enumerator > enumerators)
	Construct with name, documentation, boundary behavior, and enumerators.
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	doMakeEnumType (TPyObjPtr &&enumerators, TPyObjPtr &&kwargs) override
	Creates an enum.IntFlag-derived type with boundary behavior.
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.
TPyObjPtr	valueObject (PyObject *obj) const
	Returns the value of an enum instances as a Python object.

Detailed Description

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

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

C++ enums exported using IntFlagDefinition will generate a new enum type derived from enum.IntFlag. 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.IntFlag is used, the Python enum instances will also be valid int instances, and int instances are accepted when converting from Python to C++. Additionally, bitwise operations are supported.

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_FLAG and PY_DECLARE_INT_FLAG_* macros instead.

Usage Example:

// In header:
PY_SHADOW_INT_FLAG(LASS_DLL_EXPORT, Breakfast);
 
// In source:
PY_DECLARE_INT_FLAG_EX(Breakfast)("Breakfast", "Breakfast documentation", FlagBoundary::Keep, {
    { "EGG", Breakfast::Egg },
    { "BACON", Breakfast::Bacon },
    { "ALL", Breakfast::All },
});
 
// Add to module or class:
PY_MODULE_ENUM(mymodule, Breakfast);   // or PY_CLASS_ENUM(MyClass, Breakfast);

See also

PY_SHADOW_INT_FLAG

PY_DECLARE_INT_FLAG_NAME

PY_DECLARE_INT_FLAG_NAME_DOC

PY_DECLARE_INT_FLAG_EX

PY_MODULE_ENUM

PY_CLASS_ENUM

FlagBoundary

Definition at line 508 of file enum_definition.h.

Constructor & Destructor Documentation

IntFlagDefinition()

template<typename EnumType>

lass::python::IntFlagDefinition< EnumType >::IntFlagDefinition ( const char * name, const char * doc, FlagBoundary boundary, std::initializer_list< Enumerator > enumerators )

inline

Construct with name, documentation, boundary behavior, and enumerators.

Parameters

name	Python class name for the flag enum type (must have static storage duration)
doc	Optional docstring for the Python enum type (must have static storage duration, or nullptr)
boundary	Flag boundary behavior controlling how invalid flag combinations are handled
enumerators	List of name-value pairs defining the flag members

Note

The boundary parameter requires Python 3.11 or later. On earlier versions, only Keep is supported (which is the default if this constructor is not used).

Definition at line 527 of file enum_definition.h.

References lass::python::EnumDefinitionBase::doc(), lass::python::IntEnumDefinition< EnumType >::IntEnumDefinition(), and lass::python::EnumDefinitionBase::name().

Member Function Documentation

doMakeEnumType()

template<typename EnumType>

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

inlineoverrideprotectedvirtual

Creates an enum.IntFlag-derived type with boundary behavior.

Overrides the base class to create a flag enum with bitwise operations support.

Reimplemented from lass::python::IntEnumDefinition< EnumType >.

Definition at line 537 of file enum_definition.h.

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

addEnumerator()

template<typename EnumType>

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

inlineinherited

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

inlineinherited

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

inlineinherited

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 )

inlineoverrideprotectedvirtualinherited

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

inlineoverrideprotectedvirtualinherited

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().

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