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()`.
Constant	`_T`	Undocumented

def enum_name_callback(ctx): (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'.

Parameters
ctx:`mypy.plugin.AttributeContext`	Undocumented
Returns
`Type`	Undocumented

def enum_value_callback(ctx): (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'.

Parameters
ctx:`mypy.plugin.AttributeContext`	Undocumented
Returns
`Type`	Undocumented

ENUM_NAME_ACCESS = (source)

Undocumented

Value

{'{}.name'.format(prefix) for prefix in ENUM_BASES}|{'{}._name_'.format(prefix) ↵
for prefix in ENUM_BASES}

ENUM_VALUE_ACCESS = (source)

Undocumented

Value

{'{}.value'.format(prefix) for prefix in ENUM_BASES}|{'{}._value_'.format(prefix↵
) for prefix in ENUM_BASES}

def _extract_underlying_field_name(typ): (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.

Parameters
typ:`Type`	Undocumented
Returns
`Optional[str]`	Undocumented

def _first(it): (source)

Return the first value from any iterable.

Returns None if the iterable is empty.

Parameters
it:`Iterable[_T]`	Undocumented
Returns
`Optional[_T]`	Undocumented

def _implements_new(info): (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__.

Parameters
info:`TypeInfo`	Undocumented
Returns
`bool`	Undocumented

def _infer_value_type_with_auto_fallback(ctx, proper_type): (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"

Parameters
ctx:`mypy.plugin.AttributeContext`	Undocumented
proper_type:`Optional[ProperType]`	Undocumented
Returns
`Optional[Type]`	Undocumented

_T = (source)

Undocumented

Value

TypeVar('_T')