From 2288113be7af89bf11d1e90f00b7c7f2fbba6ea5 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:32:52 -0500 Subject: [PATCH 1/6] Add card param types to method docstrings --- adafruit_pyoa.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index b388225..85084b3 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -200,6 +200,7 @@ def _display_buttons(self, card): """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) @@ -217,6 +218,7 @@ def _display_background_for(self, card): """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) @@ -224,6 +226,7 @@ def _display_text_for(self, card): """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 @@ -249,6 +252,7 @@ def _play_sound_for(self, card): """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) @@ -263,6 +267,7 @@ def _wait_for_press(self, card): :param card: The active card Return the id of the destination card. + :type card: dict(str, str) """ button01_text = card.get("button01_text", None) button02_text = card.get("button02_text", None) From ff2a0342b91753d8d2d84551bcd4ffdd3b0aed9a Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:34:37 -0500 Subject: [PATCH 2/6] Separate param name and type in docstrings for clarity, change "Union[X, None]" typing to "X or None" --- adafruit_pyoa.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index 85084b3..602aa20 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -340,8 +340,9 @@ def display_card(self, card_num): def play_sound(self, filename, *, wait_to_finish=True, loop=False): """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 """ @@ -375,8 +376,12 @@ def play_sound(self, filename, *, wait_to_finish=True, loop=False): def set_text(self, text, color, background_color=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: @@ -408,7 +413,8 @@ def set_text(self, text, color, background_color=None): def set_background(self, filename, *, with_fade=True): """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. """ From c076dc04793e17a51d7b2d9a723c71dccc6d26b2 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:37:04 -0500 Subject: [PATCH 3/6] Add returns and return types to docstrings --- adafruit_pyoa.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index 602aa20..5ba97e6 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -268,6 +268,8 @@ def _wait_for_press(self, 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) @@ -303,6 +305,8 @@ def display_card(self, card_num): """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) @@ -460,7 +464,8 @@ def wrap_nicely(string, max_chars): :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(" ") From bd728782854734981106bab08994919cf7a4539b Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:37:29 -0500 Subject: [PATCH 4/6] Remove unnecessary text line about return in docstring --- adafruit_pyoa.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index 5ba97e6..fbc15ab 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -265,8 +265,6 @@ def _wait_for_press(self, card): """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 From 50fa60461272158367b6b4ad21c0e0b4a1f995a1 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:37:42 -0500 Subject: [PATCH 5/6] Add type hints --- adafruit_pyoa.py | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index fbc15ab..c169186 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,7 +201,7 @@ 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 @@ -214,7 +219,7 @@ 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 @@ -222,7 +227,7 @@ def _display_background_for(self, card): """ 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 @@ -248,7 +253,7 @@ 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 @@ -261,7 +266,7 @@ 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 @@ -299,7 +304,7 @@ 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 @@ -339,7 +344,7 @@ 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 filename: The filename of the sound to play. Use `None` to stop @@ -375,7 +380,7 @@ 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 text: the text to display @@ -412,7 +417,7 @@ 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 filename: The filename of the chosen background @@ -437,7 +442,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 @@ -457,7 +462,7 @@ 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. From e49d3ad754ff8db2e720e9b9675b724a91ef064e Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 15 Dec 2021 15:39:01 -0500 Subject: [PATCH 6/6] Reformatted per pre-commit --- adafruit_pyoa.py | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/adafruit_pyoa.py b/adafruit_pyoa.py index c169186..e0faf4c 100755 --- a/adafruit_pyoa.py +++ b/adafruit_pyoa.py @@ -344,7 +344,13 @@ def display_card(self, card_num: int) -> int: "Could not find card with matching 'card_id': ", destination_card_id ) - def play_sound(self, filename: Optional[str], *, wait_to_finish: bool = True, loop: bool = False) -> None: + def play_sound( + self, + filename: Optional[str], + *, + wait_to_finish: bool = True, + loop: bool = False + ) -> None: """Play a sound :param filename: The filename of the sound to play. Use `None` to stop @@ -380,7 +386,12 @@ def play_sound(self, filename: Optional[str], *, wait_to_finish: bool = True, lo self._wavfile = None self._speaker_enable.value = False - def set_text(self, text: Optional[str], color: Optional[str], background_color: Optional[int] = None) -> None: + def set_text( + self, + text: Optional[str], + color: Optional[str], + background_color: Optional[int] = None, + ) -> None: """Display the test for a card. :param text: the text to display @@ -389,7 +400,6 @@ def set_text(self, text: Optional[str], color: Optional[str], background_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() @@ -417,7 +427,9 @@ def set_text(self, text: Optional[str], color: Optional[str], background_color: self._text.background_color = background_color self._text_group.append(self._text) - def set_background(self, filename: Optional[str], *, with_fade: bool=True) -> None: + def set_background( + self, filename: Optional[str], *, with_fade: bool = True + ) -> None: """The background image to a bitmap file. :param filename: The filename of the chosen background