[WIP] Type hints

.coveragerc

@@ -16,6 +16,8 @@ exclude_lines =
 
     pass
 
+    ...
+
 # Only check coverage for source files
 include =
     automata/*/*.py

automata/base/automaton.py

@@ -2,18 +2,32 @@
 """Classes for working with all automata, including Turing machines."""
 
 import abc
+from typing import AbstractSet, Any, Dict, Generator, Mapping, NoReturn, Tuple
 
 from frozendict import frozendict
+from typing_extensions import Self
 
 import automata.base.config as global_config
 import automata.base.exceptions as exceptions
 from automata.base.utils import freeze_value
 
+AutomatonStateT = Any
+AutomatonPathT = Mapping[str, Any]
+AutomatonTransitionsT = Mapping[str, AutomatonPathT]
+
 
 class Automaton(metaclass=abc.ABCMeta):
     """An abstract base class for all automata, including Turing machines."""
 
-    def __init__(self, **kwargs):
+    __slots__: Tuple[str, ...] = tuple()
+
+    initial_state: AutomatonStateT
+    states: AbstractSet[AutomatonStateT]
+    final_states: AbstractSet[AutomatonStateT]
+    transitions: AutomatonTransitionsT
+    input_symbols: AbstractSet[str]
+
+    def __init__(self, **kwargs: Any) -> None:
         if not global_config.allow_mutable_automata:
             for attr_name, attr_value in kwargs.items():
                 object.__setattr__(self, attr_name, freeze_value(attr_value))
@@ -22,39 +36,39 @@ def __init__(self, **kwargs):
                 object.__setattr__(self, attr_name, attr_value)
         self.__post_init__()
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         if global_config.should_validate_automata:
             self.validate()
 
     @abc.abstractmethod
-    def validate(self):
+    def validate(self) -> bool:
         """Return True if this automaton is internally consistent."""
         raise NotImplementedError
 
-    def __setattr__(self, name, value):
+    def __setattr__(self, name: str, value: Any) -> NoReturn:
         """Set custom setattr to make class immutable."""
         raise AttributeError(f"This {type(self).__name__} is immutable")
 
-    def __delattr__(self, name):
+    def __delattr__(self, name: str) -> None:
         """Set custom delattr to make class immutable."""
         raise AttributeError(f"This {type(self).__name__} is immutable")
 
-    def __getstate__(self):
+    def __getstate__(self) -> Any:
         """Return the object's state, described by its input parameters"""
         return self.input_parameters
 
-    def __setstate__(self, d):
+    def __setstate__(self, d: Dict[str, Any]) -> None:
         """Restore the object state from its input parameters"""
         # Notice that the default __setstate__ method won't work
         #   because __setattr__ is disabled due to immutability
-        self.__init__(**d)
+        self.__init__(**d)  # type: ignore
 
     @abc.abstractmethod
-    def read_input_stepwise(self, input_str):
+    def read_input_stepwise(self, input_str: str) -> Generator[Any, None, None]:
         """Return a generator that yields each step while reading input."""
         raise NotImplementedError
 
-    def read_input(self, input_str):
+    def read_input(self, input_str: str) -> AutomatonStateT:
         """
         Check if the given string is accepted by this automaton.
 
@@ -65,29 +79,29 @@ def read_input(self, input_str):
             pass
         return config
 
-    def accepts_input(self, input_str):
+    def accepts_input(self, input_str: str) -> bool:
         """Return True if this automaton accepts the given input."""
         try:
             self.read_input(input_str)
             return True
         except exceptions.RejectionException:
             return False
 
-    def _validate_initial_state(self):
+    def _validate_initial_state(self) -> None:
         """Raise an error if the initial state is invalid."""
         if self.initial_state not in self.states:
             raise exceptions.InvalidStateError(
                 "{} is not a valid initial state".format(self.initial_state)
             )
 
-    def _validate_initial_state_transitions(self):
+    def _validate_initial_state_transitions(self) -> None:
         """Raise an error if the initial state has no transitions defined."""
         if self.initial_state not in self.transitions and len(self.states) > 1:
             raise exceptions.MissingStateError(
                 "initial state {} has no transitions defined".format(self.initial_state)
             )
 
-    def _validate_final_states(self):
+    def _validate_final_states(self) -> None:
         """Raise an error if any final states are invalid."""
         invalid_states = self.final_states - self.states
         if invalid_states:
@@ -98,22 +112,22 @@ def _validate_final_states(self):
             )
 
     @property
-    def input_parameters(self):
+    def input_parameters(self) -> Dict[str, Any]:
         """Return the public attributes for this automaton."""
         return {
             attr_name: getattr(self, attr_name)
             for attr_name in self.__slots__
             if not attr_name.startswith("_")
         }
 
-    def copy(self):
+    def copy(self) -> Self:
         """Create a deep copy of the automaton."""
         return self.__class__(**self.input_parameters)
 
     # Format the given value for string output via repr() or str(); this exists
     # for the purpose of displaying
 
-    def _get_repr_friendly_value(self, value):
+    def _get_repr_friendly_value(self, value: Any) -> Any:
         """
         A helper function to convert the given value / structure into a fully
         mutable one by recursively processing said structure and any of its
@@ -129,14 +143,14 @@ def _get_repr_friendly_value(self, value):
         else:
             return value
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """Return a string representation of the automaton."""
         values = ", ".join(
             f"{attr_name}={self._get_repr_friendly_value(attr_value)!r}"
             for attr_name, attr_value in self.input_parameters.items()
         )
         return f"{self.__class__.__qualname__}({values})"
 
-    def __contains__(self, input_str):
+    def __contains__(self, input_str: str) -> bool:
         """Returns whether the word is accepted by the automaton."""
         return self.accepts_input(input_str)

automata/base/config.py

@@ -1,7 +1,7 @@
 """Global configuration for the library and its primitives"""
 
 
-should_validate_automata = True
+should_validate_automata: bool = True
 # When set to True, it disables the freeze_value step
 #   -> You must guarantee that your code does not modify the automata
-allow_mutable_automata = False
+allow_mutable_automata: bool = False

automata/base/utils.py

@@ -2,11 +2,23 @@
 """Miscellaneous utility functions and classes."""
 
 from collections import defaultdict
+from itertools import count
+from typing import (
+    Any,
+    Callable,
+    DefaultDict,
+    Generic,
+    Iterable,
+    List,
+    Set,
+    Tuple,
+    TypeVar,
+)
 
 from frozendict import frozendict
 
 
-def freeze_value(value):
+def freeze_value(value: Any) -> Any:
     """
     A helper function to convert the given value / structure into a fully
     immutable one by recursively processing said structure and any of its
@@ -28,23 +40,26 @@ def freeze_value(value):
     return value
 
 
-def get_renaming_function(counter):
+def get_renaming_function(counter: count) -> Callable[[Any], int]:
     """
     A helper function that returns a renaming function to be used in the creation of
     other automata. The parameter counter should be an itertools count.
     This helper function will return the same distinct output taken from counter
     for each distinct input.
     """
 
-    new_state_name_dict = defaultdict(lambda: next(counter))
+    new_state_name_dict: DefaultDict[Any, int] = defaultdict(lambda: next(counter))
 
-    def renaming_function(item):
+    def renaming_function(item: Any) -> int:
         return new_state_name_dict[item]
 
     return renaming_function
 
 
-class PartitionRefinement:
+T = TypeVar("T")
+
+
+class PartitionRefinement(Generic[T]):
     """Maintain and refine a partition of a set of items into subsets.
     Space usage for a partition of n items is O(n), and each refine operation
     takes time proportional to the size of its argument.
@@ -53,29 +68,29 @@ class PartitionRefinement:
     https://www.ics.uci.edu/~eppstein/PADS/PartitionRefinement.py
     """
 
-    __slots__ = ("_sets", "_partition")
+    __slots__: Tuple[str, ...] = ("_sets", "_partition")
 
-    def __init__(self, items):
+    def __init__(self, items: Iterable[T]) -> None:
         """Create a new partition refinement data structure for the given
         items. Initially, all items belong to the same subset.
         """
         S = set(items)
         self._sets = {id(S): S}
         self._partition = {x: id(S) for x in S}
 
-    def get_set_by_id(self, id):
+    def get_set_by_id(self, id: int) -> Set[T]:
         """Return the set in the partition corresponding to id."""
         return self._sets[id]
 
-    def get_set_ids(self):
+    def get_set_ids(self) -> Iterable[int]:
         """Return set ids corresponding to the internal partition."""
         return self._sets.keys()
 
-    def get_sets(self):
+    def get_sets(self) -> Iterable[Set[T]]:
         """Return sets corresponding to the internal partition."""
         return self._sets.values()
 
-    def refine(self, S):
+    def refine(self, S: Iterable[T]) -> List[Tuple[int, int]]:
         """Refine each set A in the partition to the two sets
         A & S, A - S.  Return a list of pairs ids (id(A & S), id(A - S))
         for each changed set.  Within each pair, A & S will be