Improving comparison handling of Python enum.Enum vs amaranth.lib.enum.Enum

[joelpmichael]

Raising issue as requested by @whitequark out of a discussion on Mastodon at https://aus.social/@jpm/114730311602349190

I am writing test code which pairs with an implementation, and I hit a quirk around comparing the current value of a Signal() to a Python enum.Enum, when based on the same Signal:

from amaranth.lib import enum, wiring
from amaranth.lib.wiring import In, Out
...

class RunState(enum.Enum):
    NONE = 0
    STOP = 1
    LATCH = 2
    DATA = 3
    ONESHOT = 4
    CONTINUOUS = 5
...

class ShiftRegisterInputComponent(wiring.Component):
    reg_run_state: In(RunState)
...

async def testbench(ctx):
    # set initial state
    ctx.set(dut.reg_run_state, RunState.NONE)
...
    assert ctx.get(dut.reg_run_state) == RunState.NONE.value # assertion ok
    assert ctx.get(dut.reg_run_state) == RunState.NONE # assertion fails

(I'm aware how silly this test actually is now that I'm showing it to someone else, but it demonstrates the behavior)

In the Mastodon thread it was pointed out that using an amaranth.lib.enum.Enum by adding a shape= argument would Do The Right Thing, and indeed it does after converting all necessary code (e.g. manual reset to init value). It was also mentioned that providing a Python enum.Enum when a shape= argument was absent is also the desired behavior.

I'm not familiar with the underlying Amaranth code so I'm not able to provide a patch myself. Thinking about the issue, it may be desirable for the test bench ctx.get(Signal) function to return a Python enum.Enum value instead of an integer if the Signal() was constructed from a Python enum.Enum, but I suspect this may be a breaking change as existing test code may already rely on returning an int in this case. This could also be limited to just the equality operator and detecting the presence of a Python enum.Enum to be compared against, which shouldn't be a breaking change.