Add some type annotations to test the waters.

voussoirkit/backoff.py

@@ -25,7 +25,7 @@ class Backoff:
             raise ValueError(f'max must be positive, not {max}.')
         self.max = max
 
-    def current(self):
+    def current(self) -> float:
         '''
         Return the current backoff value without advancing.
         '''
@@ -34,7 +34,7 @@ class Backoff:
             y = min(y, self.max)
         return y
 
-    def next(self):
+    def next(self) -> float:
         '''
         Return the current backoff value, then advance x.
         '''
@@ -42,13 +42,13 @@ class Backoff:
         self.x += 1
         return y
 
-    def reset(self):
+    def reset(self) -> None:
         '''
         Reset x to 0.
         '''
         self.x = 0
 
-    def rewind(self, steps):
+    def rewind(self, steps) -> None:
         '''
         Subtract this many steps from x, to ease up the backoff without
         entirely resetting.

voussoirkit/bencode.py

@@ -7,7 +7,7 @@ Bencode data.
 
 https://en.wikipedia.org/wiki/Bencode
 '''
-def bencode(data):
+def bencode(data) -> bytes:
     '''
     Encode python types to bencode.
     '''

voussoirkit/betterhelp.py

@@ -10,7 +10,7 @@ HELPSTRINGS = {'', 'help', '-h', '--help'}
 
 # INTERNALS
 ################################################################################
-def can_use_bare(parser):
+def can_use_bare(parser) -> bool:
     '''
     Return true if the given parser has no required arguments, ie can run bare.
     This is used to decide whether running `> myprogram.py` should show the
@@ -29,7 +29,7 @@ def can_use_bare(parser):
     has_required_args = any(is_required(action) for action in parser._actions)
     return has_func and not has_required_args
 
-def can_use_bare_subparsers(subparser_action):
+def can_use_bare_subparsers(subparser_action) -> set:
     '''
     Return a set of subparser names which can be used bare.
     '''
@@ -39,7 +39,7 @@ def can_use_bare_subparsers(subparser_action):
     )
     return can_bares
 
-def docstring_preview(text):
+def docstring_preview(text) -> str:
     '''
     This function assumes that your docstring is formatted with a single blank
     line separating the command's primary summary and the rest of the text,
@@ -66,7 +66,7 @@ def listget(li, index, fallback=None):
     except IndexError:
         return fallback
 
-def add_previews(docstring, sub_docstrings):
+def add_previews(docstring, sub_docstrings) -> str:
     '''
     Given a primary docstring which contains {command_name} formatting elements,
     and a dict of sub_docstrings of {command_name: docstring}, insert previews
@@ -85,7 +85,7 @@ def get_subparser_action(parser):
             return action
     raise TypeError('Couldn\'t locate the SubParsersAction.')
 
-def set_alias_docstrings(sub_docstrings, subparser_action):
+def set_alias_docstrings(sub_docstrings, subparser_action) -> dict:
     '''
     When using subparser aliases:
 

voussoirkit/hms.py

@@ -3,7 +3,7 @@ import sys
 
 from voussoirkit import pipeable
 
-def hms_to_seconds(hms):
+def hms_to_seconds(hms) -> float:
     '''
     Convert hh:mm:ss string to an integer or float of seconds.
     '''
@@ -21,7 +21,7 @@ def hms_to_seconds(hms):
         seconds += float(parts[0])
     return seconds
 
-def seconds_to_hms(seconds, force_minutes=False, force_hours=False):
+def seconds_to_hms(seconds, force_minutes=False, force_hours=False) -> str:
     '''
     Convert integer number of seconds to an hh:mm:ss string.
     Only the necessary fields are used.

voussoirkit/imagetools.py

@@ -12,7 +12,7 @@ def fit_into_bounds(
         frame_width,
         frame_height,
         only_shrink=False,
-    ):
+    ) -> tuple:
     '''
     Given the w+h of the image and the w+h of the frame,
     return new w+h that fits the image into the frame
@@ -32,7 +32,7 @@ def fit_into_bounds(
 
     return (new_width, new_height)
 
-def pad_to_square(image, background_color=None):
+def pad_to_square(image, background_color=None) -> PIL.Image:
     '''
     If the given image is not already square, return a new, square image with
     additional padding on top and bottom or left and right.

voussoirkit/stringtools.py

@@ -1,14 +1,14 @@
 import re
 import unicodedata
 
-def collapse_whitespace(text):
+def collapse_whitespace(text) -> str:
     '''
     Replace all whitespace sequences with a single space and strip the ends.
     '''
     text = re.sub(r'\s+', ' ', text.strip())
     return text
 
-def comma_space_split(text):
+def comma_space_split(text) -> list:
     '''
     Split the string by commas and spaces, discarding all extra
     whitespace and blank parts.
@@ -20,7 +20,7 @@ def comma_space_split(text):
         return text
     return re.split(r'[ ,]+', text.strip())
 
-def excise(text, mark_left, mark_right):
+def excise(text, mark_left, mark_right) -> str:
     '''
     Remove the text between the left and right landmarks, including the
     landmarks themselves, and return the rest of the text.
@@ -48,7 +48,7 @@ def natural_sorter(s):
     alphanum_key = lambda key: [convert(c) for c in re.split('([0-9]+)', key)]
     return alphanum_key(s)
 
-def pascal_to_loudsnakes(text):
+def pascal_to_loudsnakes(text) -> str:
     '''
     >>> pascal_to_loudsnakes('PascalCase')
     'PASCAL_CASE'
@@ -60,12 +60,12 @@ def pascal_to_loudsnakes(text):
     text = text.upper()
     return text
 
-def remove_characters(text, characters):
+def remove_characters(text, characters) -> str:
     translator = {ord(c): None for c in characters}
     text = text.translate(translator)
     return text
 
-def remove_control_characters(text):
+def remove_control_characters(text) -> str:
     '''
     Thanks Alex Quinn
     https://stackoverflow.com/a/19016117
@@ -75,7 +75,7 @@ def remove_control_characters(text):
     '''
     return ''.join(c for c in text if unicodedata.category(c)[0] != 'C')
 
-def title_capitalize(text):
+def title_capitalize(text) -> str:
     text = text.strip().title()
     articles = [
         'a',

voussoirkit/subproctools.py

@@ -1,6 +1,6 @@
 import os
 
-def quote(arg):
+def quote(arg) -> str:
     if os.name == 'nt':
         # If the command contains comma, semicolon, or equals, only the left
         # half is considered the command and the rest is considered the first
@@ -24,7 +24,7 @@ def quote(arg):
             arg = f"'{arg}'"
         return arg
 
-def format_command(command):
+def format_command(command) -> str:
     cmd = [quote(x) for x in command]
     cmd = ' '.join(cmd)
     cmd = cmd.strip()