mypy.plugins.enums

module documentation

(source)

This file contains a variety of plugins for refining how mypy infers types of expressions involving Enums. Currently, this file focuses on providing better inference for expressions like 'SomeEnum.FOO.name' and 'SomeEnum.FOO.value'. Note that the type of both expressions will vary depending on exactly which instance of SomeEnum we're looking at. Note that this file does *not* contain all special-cased logic related to enums: we actually bake some of it directly in to the semantic analysis layer (see semanal_enum.py).

Function	`enum_name_callback`	This plugin refines the 'name' attribute in enums to act as if they were declared to be final.
Function	`enum_value_callback`	This plugin refines the 'value' attribute in enums to refer to the original underlying value. For example, suppose we have the following:
Constant	`ENUM_NAME_ACCESS`	Undocumented
Constant	`ENUM_VALUE_ACCESS`	Undocumented
Function	`_extract_underlying_field_name`	If the given type corresponds to some Enum instance, returns the original name of that enum. For example, if we receive in the type corresponding to 'SomeEnum.FOO', we return the string "SomeEnum.Foo".
Function	`_first`	Return the first value from any iterable.
Function	`_implements_new`	Check whether __new__ comes from enum.Enum or was implemented in a subclass. In the latter case, we must infer Any as long as mypy can't infer the type of _value_ from assignments in __new__.
Function	`_infer_value_type_with_auto_fallback`	Figure out the type of an enum value accounting for `auto()`.
Type Variable	`_T`	Undocumented

def enum_name_callback(ctx: mypy.plugin.AttributeContext) -> Type: (source) ¶

This plugin refines the 'name' attribute in enums to act as if they were declared to be final. For example, the expression 'MyEnum.FOO.name' normally is inferred to be of type 'str'. This plugin will instead make the inferred type be a 'str' where the last known value is 'Literal["FOO"]'. This means it would be legal to use 'MyEnum.FOO.name' in contexts that expect a Literal type, just like any other Final variable or attribute. This plugin assumes that the provided context is an attribute access matching one of the strings found in 'ENUM_NAME_ACCESS'.

def enum_value_callback(ctx: mypy.plugin.AttributeContext) -> Type: (source) ¶

This plugin refines the 'value' attribute in enums to refer to the original underlying value. For example, suppose we have the following: class SomeEnum: FOO = A() BAR = B() By default, mypy will infer that 'SomeEnum.FOO.value' and 'SomeEnum.BAR.value' both are of type 'Any'. This plugin refines this inference so that mypy understands the expressions are actually of types 'A' and 'B' respectively. This better reflects the actual runtime behavior. This plugin works simply by looking up the original value assigned to the enum. For example, when this plugin sees 'SomeEnum.BAR.value', it will look up whatever type 'BAR' had in the SomeEnum TypeInfo and use that as the inferred type of the overall expression. This plugin assumes that the provided context is an attribute access matching one of the strings found in 'ENUM_VALUE_ACCESS'.

ENUM_NAME_ACCESS = (source) ¶

Undocumented

Value

{f'{prefix}.name' for prefix in ENUM_BASES}|{f'{prefix}._name_' for prefix in EN↵
UM_BASES}

ENUM_VALUE_ACCESS = (source) ¶

Undocumented

Value

{f'{prefix}.value' for prefix in ENUM_BASES}|{f'{prefix}._value_' for prefix in ↵
ENUM_BASES}

def _extract_underlying_field_name(typ: Type) -> str|None: (source) ¶

If the given type corresponds to some Enum instance, returns the original name of that enum. For example, if we receive in the type corresponding to 'SomeEnum.FOO', we return the string "SomeEnum.Foo". This helper takes advantage of the fact that Enum instances are valid to use inside Literal[...] types. An expression like 'SomeEnum.FOO' is actually represented by an Instance type with a Literal enum fallback. We can examine this Literal fallback to retrieve the string.

def _first(it: Iterable[_T]) -> _T|None: (source) ¶

Return the first value from any iterable. Returns ``None`` if the iterable is empty.

def _implements_new(info: TypeInfo) -> bool: (source) ¶

Check whether __new__ comes from enum.Enum or was implemented in a subclass. In the latter case, we must infer Any as long as mypy can't infer the type of _value_ from assignments in __new__.

def _infer_value_type_with_auto_fallback(ctx: mypy.plugin.AttributeContext, proper_type: ProperType|None) -> Type|None: (source) ¶

Figure out the type of an enum value accounting for `auto()`. This method is a no-op for a `None` proper_type and also in the case where the type is not "enum.auto"

_T = (source) ¶

Undocumented

Value

TypeVar('_T')