Enums in the Python API (r34.2)
From r34.2, an enum value in the Python API has its own type instead of being a plain int. Most scripts and plugins written against earlier versions keep working, but a few things behave differently. Each enum has a reference page listing its values, for example MachineRole. For conversions and comparisons, see Enums in the Utility guide.
What behaves differently
| Before r34.2 | From r34.2 |
|---|---|
print(value) shows a number | shows the enum and its value’s name, e.g. <MachineRole Actor>. Use value.toString() for just the name. |
isinstance(value, int) is True | False. Use int(value) if you need a number. |
json.dumps(value) gives a number | raises TypeError. Pass int(value) or value.toString() instead. |
The JSON change affects anything that returns an enum from a plugin or through the execution API, including enums inside a returned dict or list. Convert it before returning it.
Compare with enum values, not numbers
# before
if machine.role == 3: ...
# from r34.2
if machine.role == MachineRole.Actor: ...
Comparing with an integer will still work, but using the enum value is more readable and avoids any future issues with enum reordering.
Flag enums
Flag enums such as NmosLoadType support |, & and ^, and each result is still a value of the same enum. A combination prints with each set flag’s name, e.g. <NmosLoadType node|device>.
Where to find an enum
An enum that belongs to a class is reached through that class, for example D3State.SpeedOption or ClusterAssigner.SplitType. Otherwise it is a top-level name, for example MachineRole. The enum’s reference page gives its exact name.
Prefer the enum value in new code
Some classes also expose constants that stand for enum values, for example ExpressionVariable.FloatType, which stands for ExpressionVariableType.Float. These now hold the enum value, so existing code keeps working, but they are being retired. New and updated code should use the enum value directly.
Type stub
The published d3.pyi lists each enum with its values, so an editor that reads it can complete and check them.