https://docs.python.org/3/library/enum.html https://github.com/python/cpython/blob/main/Lib/enum.py https://peps.python.org/pep-0681/ https://docs.python.org/3/library/typing.html#typing.dataclass_transform https://pypi.org/project/basicenum/ https://pypi.org/project/flufl.enum/ # Specification - What can be gleamed from introspection? - Member - Enum class - Enum metaclass - Pass in member class to specify? # Expectations ## Type checking https://typing.python.org/en/latest/spec/enums.html - [Defining](https://typing.python.org/en/latest/spec/enums.html#enum-definition) - [Class](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Type%20checkers%20should%20support%20the%20class%20syntax) - [Metaclass](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=enum.EnumType%20(or%20a%20subclass%20thereof)%20as%20a%20metaclass>) - [Function](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=the%20function%20syntax%20(in%20its%20various%20forms)%20is%20optional%3A>) - [Behaviour](https://typing.python.org/en/latest/spec/enums.html#enum-behaviors) - [Iterable](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Enum%20classes%20are%20iterable) - [Indexable](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=are%20iterable%20and-,indexable,-%2C%20and%20they%20can) - [Callable](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Calling%20an%20enum%20class) - [Final](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=They%20are%20implicitly%20%E2%80%9Cfinal%E2%80%9D.) - [Defining members](https://typing.python.org/en/latest/spec/enums.html#defining-members) - Non-members - [Class attribute w/ no assigned value](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=an%20attribute%20is%20defined%20in%20the%20class%20body%20with%20a%20type%20annotation%20but%20with%20no%20assigned%20value) - [Methods](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Type%20checker%20error-,Methods,-%2C%20callables%2C%20descriptors%20(including>) - [Callables](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Methods%2C-,callables,-%2C%20descriptors%20(including%20properties>) - [Descriptors](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=descriptors%20(including%20properties)>) - [Nested classes](<https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=Methods%2C%20callables%2C%20descriptors%20(including%20properties)%2C%20and%20nested%20classes>) - [Private name](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=attribute%20with%20a%20private%20name) via `__` - [`_ignore_`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=class%20symbol%20named-,_ignore_,-.%20This%20can%20be) (list or space-delimited string; implementation also supports comma-separated string) - [`nonmember`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=enum.member%20and-,enum.nonmember,-classes%20can%20be) class (!) - Members - Type stubs can use [`...` as a value placeholder](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=values%2C%20or%20a-,placeholder%20of%20...,-can%20be%20used) - [Assignment of another member](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=An%20attribute%20that%20is%20assigned%20the%20value%20of%20another%20member) is an alias - [`member`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=or%20newer%2C%20the-,enum.member,-and%20enum.nonmember) class (!) - Errors - [Type annotation on a member](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=A%20type%20checker%20should%20report%20an%20error%20if%20a%20type%20annotation%20is%20used%20for%20an%20enum%20member) - [`member()` and `nonmember()`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=enum.member%20and%20enum.nonmember) - [Names](https://typing.python.org/en/latest/spec/enums.html#member-names) - [`_name_` attribute](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=attribute%20_name_%20that%20contains%20the%20member%E2%80%99s%20name) - [`name` property](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=also%20have%20a-,property%20name,-that%20returns%20the) - [Values](https://typing.python.org/en/latest/spec/enums.html#member-values) - [`_value_` attribute](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=attribute%20_value_%20that%20contains%20the%20member%E2%80%99s%20value) - [`value` property](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=also%20have%20a-,property%20value,-that%20returns%20the) - [`__init__` and tuple value](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=The%20value%20of%20_value_%20can%20be%20assigned%20in%20a%20constructor%20method) - [`auto()`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=The%20class-,enum.auto,-and%20method%20_generate_next_value_) - [`_generate_next_value_` method](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=_generate_next_value_) - [`_value_`](https://typing.python.org/en/latest/spec/enums.html#member-values:~:text=an%20explicit%20type%20annotation%20for%20_value_) ## Semantics - `isinstance(Colour.RED, Colour)` - hash(Colour.RED) - `Colour.__members__` - `type(Colour.RED)` # Tool exhaustiveness ```python import enum from typing import Literal class StuffEnum(enum.Enum): A = enum.auto() B = enum.auto() type StuffLiteral = Literal["A", "B"] def test_enum(x: StuffEnum): match x: case StuffEnum.A: pass # Missing B case. def test_literal(x: StuffLiteral): match x: case "A": pass # Missing B case. ``` - [mypy](https://mypy.readthedocs.io/en/stable/error_code_list2.html#check-that-match-statements-match-exhaustively-exhaustive-match) - [Pyright](https://github.com/microsoft/pylance-release/blob/main/docs/diagnostics/reportMatchNotExhaustive.md) - [Pyrefly](https://pyrefly.org/en/docs/error-kinds/#non-exhaustive-match) - ~~ty~~