Add type hints to function signatures

For better code intelligence

tilde-train.py

@@ -6,7 +6,8 @@
 ## \__|_|_\__,_\___(_)__|_| \__,_|_|_||_|
 ##
 ## tilde.train is an instance of TerminalTrain.  It was originally developed
-## by cmccabe on tilde.town but is now maintained by vilmibm.
+## by cmccabe on tilde.town (https://tildegit.org/cmccabe/TerminalTrain) but is now
+## maintained by vilmibm.
 ##
 ## If you want to contribute code improvements, create a pull request here:
 ## https://git.tilde.town/vilmibm/tilde-train
@@ -41,6 +42,8 @@ import curses
 from signal import signal, SIGINT
 import time ## allowing the loop steps of train animation to be slowed
 import string ## for input validation
+from inspect import cleandoc
+from pathlib import Path
 
 traincarFN = ".choochoo"
 max_x = 35  ## max length of train car.
@@ -51,79 +54,84 @@ print_train = False ## print train to file (instead of the screen scroll)
 train = [""]*max_y ## empty train of correct height.
 cars = []
 
-engine = r"""        ____                      
-       |____|         ------------
-        |  |  ===     |  ------  |
-     ___|  |__| |_____| |   O  | |
-    |  |              | |__/V\_| |
-   [[  |                         |
-    |  | ------------ |   ~town  |
-    |__|______________|__________|
- //// / _\__/__\__/__\      /  \  
-////  \__/  \__/  \__/      \__/  """
-engine = engine.split("\n")
+engine = [
+  r"        ____                      ",
+  r"       |____|         ------------",
+  r"        |  |  ===     |  ------  |",
+  r"     ___|  |__| |_____| |   O  | |",
+  r"    |  |              | |__/V\_| |",
+  r"   [[  |                         |",
+  r"    |  | ------------ |   ~town  |",
+  r"    |__|______________|__________|",
+  r" //// / _\__/__\__/__\      /  \  ",
+  r"////  \__/  \__/  \__/      \__/  ",
+]
 
-caboose = r"""                        ||        
-         =============  ||        
-=========|           |==========  
-  |    ----          ----     |   
-  |   |    |        |    |    |   
-  |    ----          ----     |   
-  |    tilde.town railways    |   
-==|                           |== 
-== - /  \-/  \-----/  \-/  \ - == 
-     \__/ \__/     \__/ \__/      """
-caboose = caboose.split("\n")
-
-default_car = r""" ----------------------------  
-|                            |
-|    YOUR TRAIN CAR HERE!    |  
-|       Just create a        |  
-|      ~/.choochoo file!     |
-|   __   __        __   __   |
- - /  \-/  \------/  \-/  \ -
-   \__/ \__/      \__/ \__/"""
-default_car = default_car.split("\n")
+caboose = [
+  r"                        ||        ",
+  r"         =============  ||        ",
+  r"=========|           |==========  ",
+  r"  |    ----          ----     |   ",
+  r"  |   |    |        |    |    |   ",
+  r"  |    ----          ----     |   ",
+  r"  |    tilde.town railways    |   ",
+  r"==|                           |== ",
+  r"== - /  \-/  \-----/  \-/  \ - == ",
+  r"     \__/ \__/     \__/ \__/      ",
+]
 
+default_car = [
+  r" ---------------------------- ",
+  r"|                            |",
+  r"|    YOUR TRAIN CAR HERE!    |",
+  r"|       Just create a        |",
+  r"|      ~/.choochoo file!     |",
+  r"|   __   __        __   __   |",
+  r" - /  \-/  \------/  \-/  \ - ",
+  r"   \__/ \__/      \__/ \__/   ",
+]
 
 def print_help():
-  print("")
-  print("~ ~ Hooray! You've found the tilde.train! ~ ~")
-  print("")
-  print("To add your own car to a future train, create")
-  print("a .choochoo file in your home directory and")
-  print("make sure it is 'other' readable, for example:")
-  print("")
-  print("                         chmod 644 ~/.choochoo")
-  print("")
-  print("The file should contain an ascii drawing of a")
-  print("train car no more than " + str(max_x) + " characters wide")
-  print("and " + str(max_y) + " characters tall.")
-  print("")
-  print("Only printable ascii characters are accepted for now.")
-  print("Run the command again followed by a -t switch to test")
-  print("your .choochoo file and report any non accepted chars.")
-  print("")
-  print("Each train contains a random selection of cars")
-  print("from across tilde.town user home directories.")
-  print("Don't worry, yours will be coming around the")
-  print("bend soon!")
-  print("")
-  print("~ ~                 ~ ~                   ~ ~")
-  print("")
+  print(
+    cleandoc(
+      f"""
+      ~ ~ Hooray! You've found the tilde.train! ~ ~
+
+      To add your own car to a future train, create
+      a .choochoo file in your home directory and
+      make sure it is 'other' readable, for example:
+
+        chmod 644 ~/.choochoo
+
+      The file should contain an ascii drawing of a
+      train car no more than {max_x} characters wide
+      and {max_y} characters tall.
+
+      Only printable ascii characters are accepted for now.
+      Run the command again followed by a -t switch to test
+      your .choochoo file and report any non accepted chars.
+
+      Each train contains a random selection of cars
+      from across tilde.town user home directories.
+      Don't worry, yours will be coming around the
+      bend soon!
+
+      ~ ~                 ~ ~                   ~ ~
+      """
+    )
+  )
 
 
 def test_user_car():
-  username = getpass.getuser()
-  fname = "/home/" + username + "/" + traincarFN
+  fname = Path.home() / traincarFN
   try:
-    myfile =  open(fname, 'r')
-  except:
-    print("ERROR: Couldn't open " + fname)
-    print("Either it doesn't exist, or is not readble by the tilde.train script.")
-    exit()
+    choochoo_string = fname.read_text("utf-8")
+  except OSError as err:
+    raise OSError(
+      f"Couldn't open {fname}\n"
+      "Either it doesn't exist, or is not readble by the tilde.train script."
+    ) from err
 
-  choochoo_string = myfile.read()
   choochoo_list = choochoo_string.split("\n")
 
   car = "\n".join(choochoo_list)
@@ -158,7 +166,7 @@ def test_user_car():
     print(string.printable.strip())
     print("")
     print("Yours contained " + bad_chars)
-    exit()
+    sys.exit(1)
 
 #  print("")
 #  print("Test results:")
@@ -169,27 +177,24 @@ def test_user_car():
   if train_height > max_y+1:
     print("FAIL. Your train car is too tall.")
     print("It should be no taller than " + str(max_y) + " lines in height.")
-    myfile.close()
-    exit()
+    sys.exit(1)
 
   if train_length > max_x:
     print("FAIL. Your train car is too long.")
     print("It should be no longer than " + str(max_x) + " characters in length.")
-    myfile.close()
-    exit()
+    sys.exit(1)
 
   print("PASS. Your train car will work on the tilde.town tracks! :)")
-  myfile.close()
-  exit()
+  sys.exit()
 
-def link_car(car):
+def link_car(car: list[str]):
   for idx,row in enumerate(car):
     car[idx] = " " + row
   car[len(car)-3] = "+" + car[len(car)-3][1:]
   car[len(car)-2] = "+" + car[len(car)-2][1:]
   return car
 
-def validate_car(car):
+def validate_car(car: list[str]):
 ## this function (1) checks that a train car isn't too tall or too long
 ## (2) pads it vertically or on the right side if it is too short or if
 ## not all lines are the same length and (3) removes bad characters.
@@ -252,7 +257,7 @@ def print_all_cars():
 #      print "Cannot open " + fname # for debuggering purposes
 
 
-def chuggachugga(stdscr):
+def chuggachugga(stdscr: curses.window):
   curses.curs_set(0)
   h, w = stdscr.getmaxyx()
   x_pos = w-1
@@ -294,24 +299,24 @@ def chuggachugga(stdscr):
 def handler(signal_received, frame):
   print("Oops. The train broke.  The engineer is looking into it!")
   print("(Note: the train does not work in all terminals yet.)")
-  exit(0)
+  sys.exit(1)
 
 default_car = validate_car(default_car)
 
 if len(sys.argv) == 2 and ("-h" in sys.argv[1] or "help" in sys.argv[1]):
   print_help()
-  quit()
+  sys.exit()
 
 if len(sys.argv) == 2 and ("-t" in sys.argv[1] or "test" in sys.argv[1]):
   test_user_car()
-  quit()
+  sys.exit()
 
 if len(sys.argv) == 2 and ("-p" in sys.argv[1] or "print" in sys.argv[1]):
   print_train = True
 
 if len(sys.argv) == 2 and ("-a" in sys.argv[1] or "all" in sys.argv[1]):
   print_all_cars()
-  quit()
+  sys.exit()
 
 
 ## start a loop that collects all .choochoo files and processes on in each loop
@@ -360,7 +365,7 @@ if print_train:
   print("<pre>")
   print(train_str)
   print("</pre>")
-  quit()
+  sys.exit()
 
 pad_str = " "*train_len
 train.insert(0,pad_str)