refactor(enums)!: performance and functional improvements

[Sharp-Eyes]

Summary

This PR reworks disnake's custom enums. The existing enums come with a couple issues. First of all, the API does not match that of Python's built-in Enum class. Secondly, existing enums cannot be typed (e.g. class MyEnum(int, Enum)). This makes them both unwieldy and slower than necessary.

This PR makes the following changes:

1. Enums now adhere to the vanilla Enum API (need to double-check some field names),
2. Enums now must be typed,
3. TODO: all explicit typecasts on enums and all explicit member.value access have been removed,
   This will be deferred to a later PR.
4. implement unit tests for the new enums.

Explicitly typed enums come with the advantage that their members can be directly used in place for anything that accepts its type. For example, an int-enum member could be directly added to an integer:

>>> class Integer(int, Enum):
...     ONE = 1
...     TWO = 2

>>> # old enums:
>>> Integer.ONE.value + Integer.TWO.value + 3
6

>>> # new enums:
>>> Integer.ONE + Integer.TWO + 3
6

This comes with the advantage of not having to explicitly access value, which is both easier on the developer and faster. This also means that isinstance checks with an enum member and its type will pass, etc. Over the whole library, this means a lot of now unnecessary member access and function calls can be removed. Since enums are used extensively under the hood, this should lead to a small speed increase. A screenshot of tentative benchmarks of the projected performance increase can be seen here:

Lastly, because the API now more closely matches that of the default Enum implementation, these enums should be usable as a drop-in replacement for enums in a wide range of use cases, especially where the speed increase is necessary.

Checklist

• If code changes were made, then they have been tested
  • I have updated the documentation to reflect the changes
  • I have formatted the code properly by running task lint
  • I have type-checked the code by running task pyright
• This PR fixes an issue
• This PR adds something new (e.g. new method or parameters)
• This PR is a breaking change (e.g. methods or parameters removed/renamed)
• This PR is not a code change (e.g. documentation, README, ...)

[onerandomusername]

One thing that needs to be made sure, is that commands.option_enum() isn't broken, and that stdlib enums are supported for options but also allow internal enums. This may already be done, but I'm writing it down anyways.

[onerandomusername]

I think this can be reviewed, and as you said, we can change accessors of enums to not have the value attribute in a later pull request.

[onerandomusername]

@Chromosomologist would you please resolve conflicts on this pr and get it ready for a review?

[Sharp-Eyes]

Gotcha, we should be all good now.

[EmmmaTech]

Two things I noticed looking at the code

[onerandomusername]

@Chromosomologist would you please resolve conflicts on this pr?

[onerandomusername]

@Chromosomologist what is the status on this PR?

[Sharp-Eyes]

All changes to the underlying enum logic are done, assuming we don't run into any bugs over the testing period. As far as this PR goes, everything should be final.

As for the rest, enum subclasses' docs will need to be reintroduced as part of a separate PR, and we can then start looking into performance optimizations across the lib, too.

[onerandomusername]

lgtm

[EQUENOS]

Checked this PR before, forgot to actually approve it

[shiftinv]

Sorry for the huge review, I just spent some time trying to break things and comparing to the old and stdlib enums 😅
(note that i mostly looked at stdlib enums, so if some of these suggestions break old enum behavior we shouldn't use them)

Additionally:

• Copying and pickling enum instances breaks identity checks, which work in stdlib enums.
  Pretty sure implementing __reduce_ex__ fixes both at the same time.
• I don't quite remember, what was the verdict on having Enum.__bool__ always return True? That would certainly deviate from stdlib enums, but that's how it currently works in the old enums.
• EnumMeta.__reversed__ is missing, python falls back to calling __getitem__ with int indices, which naturally doesn't work here.
• disnake.MessageType.default in disnake.NotificationLevel is true (which technically makes sense but should be false)
• Could we run some of the tests (particularly those checking functionality that aims to emulate stdlib enums, like __contains__) with both our and the stdlib enums?
  • a parametrized fixture would work nicely, I suppose

    @pytest.fixture(params=[enums.Enum, StdlibEnum])
    def enum_type(request):
        return request.param
    
    def test_thing(enum_type: Type[enums.Enum]):
        ...

• stdlib enums validate __setattr__ and __delattr__ calls on the metaclass, maybe EnumMeta could do the same? Feels unnecessary but could be useful as a sanity check just in case.

[shiftinv]

Is __enum_type__ used for anything?
Either way the ns["__enum_type__"] assignment here won't do anything, I believe (which also means Enum.__enum_type__ is missing).

[shiftinv]

Would be great to have a comment on why Enum.__dict__ is provided here again :p

[shiftinv]

Suggested change

	bases: Tuple[Type[Any], ...] = (),
	bases: Tuple[Type[Any], ...],

[shiftinv]

Suggested change

	bases: Tuple[Type[Any], Type[Enum]],
	bases: Tuple[Type[Any], ...],

This won't always contain exactly two elements

[shiftinv]

accidental revert?

[shiftinv]

Suggested change

	class SpeakingState(int, Enum): # TODO: Docs
	class SpeakingState(int, Enum):

I guess that's not needed anymore

[shiftinv]

This seems like it could break other things... can this perhaps return a separate UnknownThing type instead, that at least has name and value attributes and perhaps even proxies the value's (and enum class's?) attributes?

Could make it pass isinstance(x, disnake.enums.SomeEnum) checks to some degree by implementing __instancecheck__ on EnumMeta, though isinstance(x, int) still wouldn't work.

tl;dr: would be great if this supported x.name, x.value, and things like x == y even if unknown

[shiftinv]

The __new__ call can raise more than TypeError, e.g. int.__new__ raises ValueError if it receives an invalid string.

On that note, should this check isinstance(val, cls.__base_type__) before calling cls.__new__(cls, val), such that try_enum(MessageType, "10") fails? (which currently works correctly as it converts "10" to 10)
Not sure about either one, tbqh

[shiftinv]

for int-valued enums, this will always call try_enum even if val is already an enum instance

[shiftinv]

Maybe also check isinstance(new, Enum) here? Will only work with the first two test cases though.
(also see my other comment about try_enum)

[onerandomusername]

@Chromosomologist will you be working on this PR?