python-stdlib/enum/enum.py: Add Enum class.

[IhorNehrutsa]

Docs in:
docs/library/enum.rst: Add Enum class. #16842
Usage example:

from enum import Enum
e = Enum({"X": 1, "Y": 2})                          # create Enum object from dictionary of key-value pairs
print(e)
print("add new key-value pair")
e.A = 'A'                                           # add new key-value pair
e.B = 'B'
print(e)
print("e.X:", e.X)                                  # get value from key
print("e.X.value:", e.X.value)                      # get value from key
print("e(e.X):", e(e.X))                            # get value from key
print("e.key_from_value(1):", e.key_from_value(1))  # get key from value
print("e.is_value(e.B):", e.is_value(e.B))
print("del e.B")
del e.B                                             # delete key-value pair
print(e)
print("e.is_value('B'):", e.is_value('B'))          # check if the value is in the Enum object
print("e.B: will raise the KeyError exception")
print(e.B)                                          # raise an exception due to no such a key attribute

Output is:

Enum({'Y': 2, 'X': 1})
add new key-value pair
Enum({'A': 'A', 'B': 'B', 'Y': 2, 'X': 1})
e.X: 1
e.X.value: 1
e(e.X): 1
e.key_from_value(1): Enum.X
e.is_value(e.B): True
del e.B
Enum({'A': 'A', 'Y': 2, 'X': 1})
e.is_value('B'): False
e.B: will raise the KeyError exception
Traceback (most recent call last):
File "<stdin>", line 234, in <module>
File "<stdin>", line 126, in __getattr__
KeyError: no such attribute: B

EDITED:
Inspired by @shariltumin Dot class from the Way to use dot notation to refer to states in a state machine #15694
and @njourdane enum() func from the Request for package: micropython-enum #269

[IhorNehrutsa]

Usage example::

from enum import Enum

class State(Enum):
  Stop = 10
  Run = 20
  Ready = 30

state = State()
print("state:", State())

current_state = state.Stop
print("current_state:", current_state, state.key_from_value(current_state))
if current_state == state.Stop:
  print(" Stop state")
if current_state != state.Ready:
  print(" Not a Ready state")
  print(" Run!")
  current_state = state.Run
print("current_state:", current_state, state.key_from_value(current_state))
# some process
i = -1
while current_state != state.Ready:
  i += 1
  if state.is_value(i):
      if state(i) == state.Ready:
          current_state = state.Ready
  print(".", end="")
print()
print("current_state:", current_state, state.key_from_value(current_state))
print("Done!")

Output is::

state: State({'Ready': 30, 'Stop': 10, 'Run': 20})
current_state: 10 State.Stop
Stop state
Not a Ready state
Run!
current_state: 20 State.Run
...............................
current_state: 30 State.Ready
Done!

[dpgeorge]

Thanks for the contribution, this looks pretty good!

Did you implement this from scratch, or copy parts from CPython's implementation? I'm just wondering about licensing and copyright.

Can you please add the test to the CI, in tools/ci.sh inside the function ci_package_tests_run.

[IhorNehrutsa]

Did you implement this from scratch, or copy parts from CPython's implementation?

I just saw CPython Enum. It looks like incredible magic. :-)

[dpgeorge]

I just saw CPython Enum. It looks like incredible magic. :-)

That doesn't really answer the question. Did you copy this implementation from CPython?

Also, please make sure the CI all passes, there's currently a failure.

[IhorNehrutsa]

| Did you implement this from scratch, or copy parts from CPython's implementation?

No, I didn't use CPython implementation.

It was inspired by @shariltumin Dot class from the Way to use dot notation to refer to states in a state machine #15694
and @njourdane enum() func from the Request for package: micropython-enum #269

[IhorNehrutsa]

Should I squash commits?

[dpgeorge]

I tried to run this test under CPython 3.12.2 but it doesn't work, for many reasons. And it should run under CPython so we can test that the implementation of MicroPython's enum matches the CPython enum.

For example, enum does not exist in the enum CPython module. Which version of CPython were you testing against?

[dpgeorge]

CPython cannot create enums in this way.

[dpgeorge]

CPython requires a value in the constructor here.

[dpgeorge]

CPython doesn't allow such an argument to the constructor.

[dpgeorge]

CPython doesn't allow calling an enum.

[dpgeorge]

CPython doesn't have key_from_value().

[dpgeorge]

CPython doesn't allow inheriting enums from each other.

[dpgeorge]

CPython doesn't have __len__ on an enum.

[dpgeorge]

CPython enums don't have keys/values/items methods.