add static type checking hints

Author: bckohan

CONTRIBUTING.rst

@@ -26,8 +26,7 @@ Installation
 ------------
 
 `django-enum` uses Poetry_ for environment, package and dependency
-management. Poetry_ greatly simplifies environment bootstrapping. Once it's
-installed:
+management:
 
 .. code-block::
 
@@ -60,6 +59,7 @@ justified is acceptable:
 
     poetry run isort django_enum
     poetry run pylint django_enum
+    poetry run mypy django_enum
     poetry run doc8 -q doc
     poetry check
     poetry run pip check

django_enum/choices.py

@@ -73,10 +73,10 @@ def __init__(self, *args, **kwargs):
                 f'installed.'
             )
 
-    DjangoSymmetricMixin = MissingEnumProperties
+    DjangoSymmetricMixin = MissingEnumProperties  # type: ignore
 
 
-    class DjangoEnumPropertiesMeta(ChoicesMeta):
+    class DjangoEnumPropertiesMeta(ChoicesMeta):  # type: ignore
         """
         Throw error if metaclass is used without enum-properties
 
@@ -89,21 +89,21 @@ def __init__(cls, *args, **kwargs):  # pylint: disable=W0231
                 f'installed.'
             )
 
-    class TextChoices(
+    class TextChoices(  # type: ignore
         DjangoSymmetricMixin,
         str,
         Choices
     ):
         """Raises ImportError on class definition"""
 
-    class IntegerChoices(
+    class IntegerChoices(  # type: ignore
         DjangoSymmetricMixin,
         int,
         Choices
     ):
         """Raises ImportError on class definition"""
 
-    class FloatChoices(
+    class FloatChoices(  # type: ignore
         DjangoSymmetricMixin,
         float,
         Choices

django_enum/fields.py

@@ -1,21 +1,50 @@
 """
 Support for Django model fields built from enumeration types.
 """
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+)
+
 from django.core.exceptions import ValidationError
 from django.db.models import (
     BigIntegerField,
     CharField,
     Choices,
+    Field,
     FloatField,
     IntegerField,
+    Model,
     PositiveBigIntegerField,
     PositiveIntegerField,
     PositiveSmallIntegerField,
     SmallIntegerField,
 )
 
+T = TypeVar('T')
+
 
-class EnumMixin:
+def with_typehint(baseclass: Type[T]) -> Type[T]:
+    """
+    Change inheritance to add Field type hints when . This is just more simple
+    than defining a Protocols - revisit if Django provides Field protocol -
+    should also just be a way to create a Protocol from a class?
+    """
+    if TYPE_CHECKING:
+        return baseclass  # pragma: no cover
+    return object  # type: ignore
+
+
+class EnumMixin(
+    # why can't mypy handle the line below?
+    with_typehint(Field)  # type: ignore
+):
     """
     This mixin class turns any Django database field into an enumeration field.
     It works by overriding validation and pre/post database hooks to validate
@@ -30,23 +59,32 @@ class EnumMixin:
         field type.
     """
 
-    enum = None
-    strict = True
+    enum: Optional[Type[Choices]] = None
+    strict: bool = True
 
-    def _coerce_to_value_type(self, value):
+    def _coerce_to_value_type(self, value: Any) -> Choices:
         """Coerce the value to the enumerations value type"""
         # note if enum type is int and a floating point is passed we could get
         # situations like X.xxx == X - this is acceptable
-        return type(self.enum.values[0])(value)
+        if self.enum:
+            return type(self.enum.values[0])(value)
+        # can't ever reach this - just here to make type checker happy
+        return value  # pragma: no cover
 
-    def __init__(self, *args, enum=None, strict=strict, **kwargs):
+    def __init__(
+            self,
+            *args,
+            enum: Optional[Type[Choices]] = None,
+            strict: bool = strict,
+            **kwargs
+    ):
         self.enum = enum
         self.strict = strict if enum else False
         if self.enum is not None:
             kwargs.setdefault('choices', enum.choices if enum else [])
         super().__init__(*args, **kwargs)
 
-    def _try_coerce(self, value):
+    def _try_coerce(self, value: Any) -> Union[Choices, Any]:
         if self.enum is not None and not isinstance(value, self.enum):
             try:
                 value = self.enum(value)
@@ -61,7 +99,7 @@ def _try_coerce(self, value):
                         ) from err
         return value
 
-    def deconstruct(self):
+    def deconstruct(self) -> Tuple[str, str, List, dict]:
         """
         Preserve enum class for migrations. Strict is omitted because
         reconstructed fields are *always* non-strict sense enum is null.
@@ -74,7 +112,7 @@ def deconstruct(self):
 
         return name, path, args, kwargs
 
-    def get_prep_value(self, value):
+    def get_prep_value(self, value: Any) -> Any:
         """
         Convert the database field value into the Enum type.
 
@@ -105,10 +143,10 @@ def get_db_prep_value(self, value, connection, prepared=False):
 
     def from_db_value(
             self,
-            value,
+            value: Any,
             expression,  # pylint: disable=W0613
             connection  # pylint: disable=W0613
-    ):
+    ) -> Any:
         """
         Convert the database field value into the Enum type.
 
@@ -118,7 +156,7 @@ def from_db_value(
             return value
         return self._try_coerce(value)
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Union[Choices, Any]:
         """
         Converts the value in the enumeration type.
 
@@ -139,7 +177,7 @@ def to_python(self, value):
                 f"'{value}' is not a valid {self.enum.__name__}."
             ) from err
 
-    def validate(self, value, model_instance):
+    def validate(self, value: Any, model_instance: Model):
         """
         Validates the field as part of model clean routines. Runs super class
         validation routines then tries to convert the value to a valid
@@ -231,7 +269,7 @@ class _EnumFieldMetaClass(type):
 
     SUPPORTED_PRIMITIVES = {int, str, float}
 
-    def __new__(mcs, enum):  # pylint: disable=R0911
+    def __new__(mcs, enum: Choices) -> Field:  # pylint: disable=R0911
         """
         Construct a new Django Field class given the Enumeration class. The
         correct Django field class to inherit from is determined based on the
@@ -241,12 +279,13 @@ def __new__(mcs, enum):  # pylint: disable=R0911
         """
         assert issubclass(enum, Choices), \
             f'{enum} must inherit from {Choices}!'
-        primitive = mcs.SUPPORTED_PRIMITIVES.intersection(set(enum.__mro__))
-        assert len(primitive) == 1, f'{enum} must inherit from exactly one ' \
-                                    f'supported primitive type ' \
-                                    f'{mcs.SUPPORTED_PRIMITIVES}'
+        primitives = mcs.SUPPORTED_PRIMITIVES.intersection(set(enum.__mro__))
+        assert len(primitives) == 1, f'{enum} must inherit from exactly one ' \
+                                     f'supported primitive type ' \
+                                     f'{mcs.SUPPORTED_PRIMITIVES}, ' \
+                                     f'encountered: {primitives}.'
 
-        primitive = list(primitive)[0]
+        primitive = list(primitives)[0]
 
         if primitive is float:
             return EnumFloatField
@@ -271,7 +310,11 @@ def __new__(mcs, enum):  # pylint: disable=R0911
         return EnumCharField
 
 
-def EnumField(enum, *field_args, **field_kwargs):  # pylint: disable=C0103
+def EnumField(  # pylint: disable=C0103
+        enum: Choices,
+        *field_args,
+        **field_kwargs
+) -> Field:
     """
     Some syntactic sugar that wraps the enum field metaclass so that we can
     cleanly create enums like so:

django_enum/filters.py

@@ -1,10 +1,13 @@
 """Support for django-filter"""
+from typing import Tuple, Type
+
+from django.db.models import Field as ModelField
+from django.forms.fields import Field as FormField
 from django_enum.fields import EnumMixin
 from django_enum.forms import EnumChoiceField
 
 try:
-    from django_filters import ChoiceFilter, filterset
-
+    from django_filters import ChoiceFilter, Filter, filterset
 
     class EnumFilter(ChoiceFilter):
         """
@@ -28,7 +31,7 @@ class Color(TextChoices, s('rgb'), s('hex', case_fold=True)):
         parameter values from any of the symmetric properties: ?color=Red,
         ?color=ff0000, etc...
         """
-        field_class = EnumChoiceField
+        field_class: FormField = EnumChoiceField
 
         def __init__(self, *, enum, **kwargs):
             self.enum = enum
@@ -42,7 +45,11 @@ class FilterSet(filterset.FilterSet):
         default instead of ``ChoiceFilter``.
         """
         @classmethod
-        def filter_for_lookup(cls, field, lookup_type):
+        def filter_for_lookup(
+                cls,
+                field: ModelField,
+                lookup_type: str
+        ) -> Tuple[Type[Filter], dict]:
             """For EnumFields use the EnumFilter class by default"""
             if isinstance(field, EnumMixin) and getattr(field, 'enum', None):
                 return EnumFilter, {'enum': field.enum}
@@ -51,13 +58,14 @@ def filter_for_lookup(cls, field, lookup_type):
 
 except (ImportError, ModuleNotFoundError):
 
-    class MissingDjangoFilters:
+    class _MissingDjangoFilters:
         """Throw error if filter support is used without django-filter"""
+
         def __init__(self, *args, **kwargs):
             raise ImportError(
                 f'{self.__class__.__name__} requires django-filter to be '
                 f'installed.'
             )
 
-    EnumFilter = MissingDjangoFilters
-    FilterSet = MissingDjangoFilters
+    EnumFilter = _MissingDjangoFilters  # type: ignore
+    FilterSet = _MissingDjangoFilters  # type: ignore

django_enum/forms.py

@@ -1,7 +1,10 @@
 """Enumeration support for django model forms"""
+from typing import Any, Dict, Iterable, List, Tuple, Type, Union
+
 from django.core.exceptions import ValidationError
+from django.db.models import Choices
 from django.forms.fields import ChoiceField
-from django.forms.widgets import Select
+from django.forms.widgets import Select, Widget
 
 # pylint: disable=R0801
 
@@ -20,12 +23,13 @@ class NonStrictSelect(Select):
     A Select widget for non-strict EnumChoiceFields that includes any existing
     non-conforming value as a choice option.
     """
+    choices: Iterable[Tuple[Any, str]]
 
     def render(self, *args, **kwargs):
         """Before rendering if we're a non strict field and our value is """
-        value = kwargs.get('value')
+        value: Any = kwargs.get('value')
         if value not in self.attrs.get('empty_values', []):
-            self.choices = list(self.choices) + [(value, value)]
+            self.choices = list(self.choices) + [(value, str(value))]
         return super().render(*args, **kwargs)
 
 
@@ -48,16 +52,18 @@ class EnumChoiceField(ChoiceField):
     :param kwargs: Any additional parameters to pass to ChoiceField base class.
     """
 
-    strict = True
-    empty_value = ''
+    enum: Type[Choices]
+    strict: bool = True
+    empty_value: Any = ''
+    empty_values: List[Any]
 
     def __init__(
             self,
-            enum,
+            enum: Type[Choices],
             *,
-            empty_value=_Unspecified,
-            strict=strict,
-            choices=(),
+            empty_value: Any = _Unspecified,
+            strict: bool = strict,
+            choices: Iterable[Tuple[Any, str]] = (),
             **kwargs
     ):
         self.enum = enum
@@ -91,11 +97,11 @@ def __init__(
                             f'non-conflicting empty_value.'
                         )
 
-    def _coerce_to_value_type(self, value):
+    def _coerce_to_value_type(self, value: Any) -> Any:
         """Coerce the value to the enumerations value type"""
         return type(self.enum.values[0])(value)
 
-    def _coerce(self, value):
+    def _coerce(self, value: Any) -> Union[Choices, Any]:
         """
         Attempt conversion of value to an enumeration value and return it
         if successful.
@@ -127,20 +133,13 @@ def _coerce(self, value):
                         ) from err
         return value
 
-    def widget_attrs(self, widget):
+    def widget_attrs(self, widget: Widget) -> Dict[Any, Any]:
         attrs = super().widget_attrs(widget)
         attrs.setdefault('empty_value', self.empty_value)
         attrs.setdefault('empty_values', self.empty_values)
         return attrs
 
-    def clean(self, value):
-        """
-        Validate the given value and return its "cleaned" value as an
-        appropriate Python object. Raise ValidationError for any errors.
-        """
-        return super().clean(self._coerce(value))
-
-    def prepare_value(self, value):
+    def prepare_value(self, value: Any) -> Any:
         """Must return the raw enumeration value type"""
         value = self._coerce(value)
         return super().prepare_value(
@@ -149,11 +148,11 @@ def prepare_value(self, value):
             else value
         )
 
-    def to_python(self, value):
+    def to_python(self, value: Any) -> Union[Choices, Any]:
         """Return the value as its full enumeration object"""
         return self._coerce(value)
 
-    def valid_value(self, value):
+    def valid_value(self, value: Any) -> bool:
         """Return false if this value is not valid"""
         try:
             self._coerce(value)