Static Type Checking: Enums

[nathanwilliams-ct]

Buildstream implements a custom FastEnum[1].
mypy only supports enum.Enum (and it's official variations) when it comes to doing static type checks on enums [2].
We can't subclass Enum in FastEnum to make mypy happy, because Enum doesn't allow subclassing [3].
So we end up with a bunch of str, int etc around the codebase,
instead of the appropriate Enum classes like OverlapAction or _Scope which are usually recorded separately in the doc strings.
This means we don't get proper static type checking on our Enums :( .
With stub files [4][5] we can lie to mypy about what type the Enum classes are[6],
so the type hints around the codebase are now correct be corrected.
Now we can have proper static type checking on the custom Enums, Yay!

So

class OverlapAction(FastEnum):
    ERROR: str
    WARNING: str
    IGNORE: str

gets stubbed as

from enum import Enum
class OverlapAction(Enum):
    ERROR: str
    WARNING: str
    IGNORE: str

[1] src/buildstream/types.py#L32
[2] https://mypy.readthedocs.io/en/stable/literal_types.html#enums
[3] https://docs.python.org/3/howto/enum.html#restricted-enum-subclassing
[4] https://typing.python.org/en/latest/guides/writing_stubs.html
[5] https://mypy.readthedocs.io/en/stable/stubgen.html
[6] python/mypy#3217