diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index b388225..e0faf4c 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -48,6 +48,11 @@ from adafruit_button import Button import terminalio +try: + from typing import Dict, Optional, List +except ImportError: + pass + __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_PYOA.git" @@ -56,7 +61,7 @@ class PYOA_Graphics: # pylint: disable=too-many-instance-attributes """A choose your own adventure game framework.""" - def __init__(self): + def __init__(self) -> None: self.root_group = displayio.Group() self._display = board.DISPLAY self._background_group = displayio.Group() @@ -113,7 +118,7 @@ def __init__(self): self._right_button = None self._middle_button = None - def load_game(self, game_directory): + def load_game(self, game_directory: str) -> None: """Load a game. :param str game_directory: where the game files are stored @@ -183,7 +188,7 @@ def load_game(self, game_directory): except OSError as err: raise OSError("Could not open game file " + self._gamefilename) from err - def _fade_to_black(self): + def _fade_to_black(self) -> None: """Turn down the lights.""" if self.mouse_cursor: self.mouse_cursor.is_hidden = True @@ -196,10 +201,11 @@ def _fade_to_black(self): if self.mouse_cursor: self.mouse_cursor.is_hidden = False - def _display_buttons(self, card): + def _display_buttons(self, card: Dict[str, str]) -> None: """Display the buttons of a card. :param card: The active card + :type card: dict(str, str) """ button01_text = card.get("button01_text", None) button02_text = card.get("button02_text", None) @@ -213,17 +219,19 @@ def _display_buttons(self, card): self._button_group.append(self._right_button) self._button_group.append(self._left_button) - def _display_background_for(self, card): + def _display_background_for(self, card: Dict[str, str]) -> None: """If there's a background on card, display it. :param card: The active card + :type card: dict(str, str) """ self.set_background(card.get("background_image", None), with_fade=False) - def _display_text_for(self, card): + def _display_text_for(self, card: Dict[str, str]) -> None: """Display the main text of a card. :param card: The active card + :type card: dict(str, str) """ text = card.get("text", None) text_color = card.get("text_color", 0x0) # default to black @@ -245,10 +253,11 @@ def _display_text_for(self, card): self.set_text(text, text_color, background_color=text_background_color) - def _play_sound_for(self, card): + def _play_sound_for(self, card: Dict[str, str]) -> None: """If there's a sound, start playing it. :param card: The active card + :type card: dict(str, str) """ sound = card.get("sound", None) loop = card.get("sound_repeat", False) @@ -257,12 +266,13 @@ def _play_sound_for(self, card): print("Loop:", loop) self.play_sound(sound, wait_to_finish=False, loop=loop) - def _wait_for_press(self, card): + def _wait_for_press(self, card: Dict[str, str]) -> str: """Wait for a button to be pressed. :param card: The active card - - Return the id of the destination card. + :type card: dict(str, str) + :return: The id of the destination card + :rtype: str """ button01_text = card.get("button01_text", None) button02_text = card.get("button02_text", None) @@ -294,10 +304,12 @@ def _wait_for_press(self, card): return card.get("button02_goto_card_id", None) time.sleep(0.1) - def display_card(self, card_num): + def display_card(self, card_num: int) -> int: """Display and handle input on a card. :param int card_num: the index of the card to process + :return: the card number of the selected card + :rtype: int """ card = self._game[card_num] print(card) @@ -332,11 +344,18 @@ def display_card(self, card_num): "Could not find card with matching 'card_id': ", destination_card_id ) - def play_sound(self, filename, *, wait_to_finish=True, loop=False): + def play_sound( + self, + filename: Optional[str], + *, + wait_to_finish: bool = True, + loop: bool = False + ) -> None: """Play a sound - :param Union(None,str) filename: The filename of the sound to play. Use `None` to stop + :param filename: The filename of the sound to play. Use `None` to stop playing anything. + :type filename: str or None :param bool wait_to_finish: Whether playing the sound should block :param bool loop: Whether the sound should loop """ @@ -367,12 +386,20 @@ def play_sound(self, filename, *, wait_to_finish=True, loop=False): self._wavfile = None self._speaker_enable.value = False - def set_text(self, text, color, background_color=None): + def set_text( + self, + text: Optional[str], + color: Optional[str], + background_color: Optional[int] = None, + ) -> None: """Display the test for a card. - :param Union(None,str) text: the text to display - :param Union(None,int) color: the text color - + :param text: the text to display + :type text: str or None + :param color: the text color + :type color: str or None + :param background_color: the background color of the text + :type background_color: int or None """ if self._text_group: self._text_group.pop() @@ -400,10 +427,13 @@ def set_text(self, text, color, background_color=None): self._text.background_color = background_color self._text_group.append(self._text) - def set_background(self, filename, *, with_fade=True): + def set_background( + self, filename: Optional[str], *, with_fade: bool = True + ) -> None: """The background image to a bitmap file. - :param Union(None,str) filename: The filename of the chosen background + :param filename: The filename of the chosen background + :type filename: str or None :param bool with_fade: If `True` fade out the backlight while loading the new background and fade in the backlight once completed. """ @@ -424,7 +454,7 @@ def set_background(self, filename, *, with_fade=True): self._display.refresh(target_frames_per_second=60) self.backlight_fade(1.0) - def backlight_fade(self, to_light): + def backlight_fade(self, to_light: float) -> None: """ Adjust the TFT backlight. Fade from the current value to the ``to_light`` value @@ -444,12 +474,13 @@ def backlight_fade(self, to_light): # return a list of lines with wordwrapping @staticmethod - def wrap_nicely(string, max_chars): + def wrap_nicely(string: str, max_chars: int) -> List[str]: """A helper that will return a list of lines with word-break wrapping. :param str string: The text to be wrapped. :param int max_chars: The maximum number of characters on a line before wrapping. - + :return: The list of lines + :rtype: list(str) """ # string = string.replace('\n', '').replace('\r', '') # strip confusing newlines words = string.split(" ")