📇 Add type hints to all the code

Note that, as of the time of writing, straightforward type checks are fine,
but strict checking still fails due to
python/mypy#7316

Author: davep

journeys/commands.py

@@ -1,5 +1,13 @@
 """Module that provides a method of playing robot commands."""
 
+##############################################################################
+# Python imports.
+from typing import List
+
+##############################################################################
+# Local imports.
+from .state import State
+
 ##############################################################################
 # Exception used to convey problems with the commands.
 class CommandException( Exception ):
@@ -15,7 +23,7 @@ class CommandException( Exception ):
 
 ##############################################################################
 # Perform a list of commands starting with an initial state.
-def perform( commands, state ):
+def perform( commands: List[ str ], state: State ) -> State:
     """Perform a list of commands for a robot.
 
     :param list commands: The list of commands to perform.

journeys/journey.py

@@ -3,6 +3,7 @@
 ##############################################################################
 # General imports.
 from dataclasses import dataclass
+from typing      import List
 
 ##############################################################################
 # Local imports.
@@ -27,10 +28,10 @@ class Journey:
     end_state: State
 
     #: The commands for the robot.
-    commands: list
+    commands: List[ str ]
 
     @property
-    def is_valid( self ):
+    def is_valid( self ) -> bool:
         """Does the journey data look valid?
 
         :type: bool

journeys/reader.py

@@ -3,6 +3,7 @@
 ##############################################################################
 # General imports.
 import re
+from   typing import List, Iterator, TextIO
 
 ##############################################################################
 # Local imports.
@@ -26,7 +27,7 @@ class InvalidCommands( Exception ):
 
 ##############################################################################
 # Parse the given line as state.
-def parse_state( text ):
+def parse_state( text: str ) -> State:
     """Parse a given line of text as a robot state.
 
     :param str text: The text to parse.
@@ -53,12 +54,12 @@ def parse_state( text ):
 
 ##############################################################################
 # Parse a command line.
-def parse_commands( text ):
+def parse_commands( text: str ) -> List[ str ]:
     """Parse a line of text as robot commands.
 
     :param str text: The line of text to parse.
     :returns: A list of commands to perform.
-    :rtype: list
+    :rtype: list[ str ]
     :raises InvalidCommands:
     """
 
@@ -71,11 +72,11 @@ def parse_commands( text ):
 
 ##############################################################################
 # Class for reading in the journey input.
-def journeys( source ):
+def journeys( source: TextIO ) -> Iterator[ Journey ]:
     """Read the journeys found in the given source.
 
-    :param TextIOBase source: A stream that is a source of journeys.
-    :returns: A journey generator.
+    :param TextIO source: A stream that is a source of journeys.
+    :returns: A journey iterator.
     :rtype: Iterator[Journey]
     """
 

journeys/state.py

@@ -3,6 +3,7 @@
 ##############################################################################
 # General imports.
 from dataclasses import dataclass, replace
+from typing      import List
 
 ##############################################################################
 # Exception used to convey problems with the State class.
@@ -49,7 +50,7 @@ class State:
     #: Direction the robot is facing.
     facing: str = EAST
 
-    def _turn( self, compass ):
+    def _turn( self, compass: List[ str ] ) -> State:
         """Make a 90 degree turn on the given compass.
 
         :param list compass: List of compass directions to turn through.
@@ -58,23 +59,23 @@ def _turn( self, compass ):
         """
         return replace( self, facing=compass[ compass.index( self.facing ) - 1 ] )
 
-    def left( self ):
+    def left( self ) -> State:
         """Make a 90 degree turn to the left.
 
         :returns: A new state.
         :rtype: State
         """
         return self._turn( COMPASS )
 
-    def right( self ):
+    def right( self ) -> State:
         """Make a 90 degree turn to the right.
 
         :returns: A new state.
         :rtype: State
         """
         return self._turn( list( reversed( COMPASS ) ) )
 
-    def forward( self ):
+    def forward( self ) -> State:
         """Move forward one position.
 
         :returns: self
@@ -96,7 +97,7 @@ def forward( self ):
         # We appear to have being facing in a direction we don't know about.
         raise StateException( f"Facing in unknown direction '{self.facing}'" )
 
-    def __str__( self ):
+    def __str__( self ) -> str:
         """Return a string representation of the state."""
         return f"{self.x_pos} {self.y_pos} {self.facing}"