Static Type Checking: Enums by nathanwilliams-ct · Pull Request #2153 · apache/buildstream

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct · 2026-07-17T08:53:45Z

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

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

juergbi

LGTM. Ideally, we'd have a small script to automate the generation of type.pyi and then we could run that in CI to verify that it's up-to-date. However, I think regeneration is reasonably simple as is and there shouldn't be a functional risk with an outdated type.pyi, so I think it's fine to merge this as is.

wsalmonct · 2026-08-03T10:11:06Z

 return cls._value_to_entry[value]
 except KeyError:
- if type(value) is cls: # pylint: disable=unidiomatic-typecheck
+ if isinstance(value, cls): # pylint: disable=unidiomatic-typecheck


AFAICT your are now doing this right.
https://pylint.pycqa.org/en/latest/user_guide/messages/convention/unidiomatic-typecheck.html
Suggested change
ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
ifisinstance(value, cls):
So you dont need to disable the lint.

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

nathanwilliams-ct requested review from BenjaminSchubert, abderrahim, cs-shadow, gtristan and juergbi as code owners July 17, 2026 08:53

nathanwilliams-ct marked this pull request as draft July 17, 2026 08:54

nathanwilliams-ct added 2 commits July 17, 2026 10:00

docs: Add details about static type checking
6115da1

nathanwilliams-ct force-pushed the nathan/enum-static-type-checking branch from b81428e to 6115da1Compare July 17, 2026 09:00

nathanwilliams-ct marked this pull request as ready for review July 17, 2026 09:01

nathanwilliams-ct mentioned this pull request Jul 17, 2026
Shell API and CLI: Add option for staging additional runtime targets #2147
Open

juergbi approved these changes Jul 24, 2026
View reviewed changes

juergbi merged commit ad6b437 into apache:masterJul 28, 2026
18 checks passed

wsalmonct reviewed Aug 3, 2026
View reviewed changes

Comment threadsrc/buildstream/_pipeline.py

	ifisinstance(value, cls):# pylint: disable=unidiomatic-typecheck
	ifisinstance(value, cls):

Uh oh!

Conversation

nathanwilliams-ct commented Jul 17, 2026

Uh oh!

juergbi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wsalmonctAug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

nathanwilliams-ct commented Jul 17, 2026

Uh oh!

juergbi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wsalmonctAug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

nathanwilliams-ct commented Jul 17, 2026

Uh oh!

juergbi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wsalmonctAug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

nathanwilliams-ct commented Jul 17, 2026

Uh oh!

juergbi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wsalmonctAug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants