Merge pull request #170 from rgrizzell/main

Add typing and documentation for ScrollingLabel

Author: tekktrik

adafruit_display_text/scrolling_label.py

@@ -26,36 +26,40 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Display_Text.git"
 
+try:
+    from typing import Optional
+    from fontio import FontProtocol
+except ImportError:
+    pass
+
 import time
 from adafruit_display_text import bitmap_label
 
 
 class ScrollingLabel(bitmap_label.Label):
-
-    """
-    ScrollingLabel - A fixed-width label that will scroll to the left
+    """ScrollingLabel - A fixed-width label that will scroll to the left
     in order to show the full text if it's larger than the fixed-width.
 
     :param font: The font to use for the label.
-    :param max_characters: The number of characters that sets the  fixed-width. Default is 10.
-    :param text: The full text to show in the label. If this is longer than
-     `max_characters` then the label will scroll to show everything.
-    :param animate_time: The number of seconds in between scrolling animation
+    :type: ~FontProtocol
+    :param int max_characters: The number of characters that sets the fixed-width. Default is 10.
+    :param str text: The full text to show in the label. If this is longer than
+     ``max_characters`` then the label will scroll to show everything.
+    :param float animate_time: The number of seconds in between scrolling animation
      frames. Default is 0.3 seconds.
-    :param current_index: The index of the first visible character in the label.
-     Default is 0, the first character. Will increase while scrolling.
-    """
+    :param int current_index: The index of the first visible character in the label.
+     Default is 0, the first character. Will increase while scrolling."""
 
     # pylint: disable=too-many-arguments
     def __init__(
         self,
-        font,
-        max_characters=10,
-        text="",
-        animate_time=0.3,
-        current_index=0,
+        font: FontProtocol,
+        max_characters: int = 10,
+        text: Optional[str] = "",
+        animate_time: Optional[float] = 0.3,
+        current_index: Optional[int] = 0,
         **kwargs
-    ):
+    ) -> None:
 
         super().__init__(font, **kwargs)
         self.animate_time = animate_time
@@ -69,13 +73,13 @@ def __init__(
 
         self.update()
 
-    def update(self, force=False):
-        """
-        Attempt to update the display. If `animate_time` has elapsed since
+    def update(self, force: bool = False) -> None:
+        """Attempt to update the display. If ``animate_time`` has elapsed since
         previews animation frame then move the characters over by 1 index.
         Must be called in the main loop of user code.
 
-        :param force: whether to ignore `animation_time` and force the update. Default is False.
+        :param bool force: whether to ignore ``animation_time`` and force the update.
+         Default is False.
         :return: None
         """
         _now = time.monotonic()
@@ -110,33 +114,31 @@ def update(self, force=False):
             return
 
     @property
-    def current_index(self):
-        """
-        Index of the first visible character.
+    def current_index(self) -> int:
+        """Index of the first visible character.
 
-        :return int: the current index
+        :return int: The current index
         """
         return self._current_index
 
     @current_index.setter
-    def current_index(self, new_index):
+    def current_index(self, new_index: int) -> None:
         if new_index < len(self.full_text):
             self._current_index = new_index
         else:
             self._current_index = new_index % len(self.full_text)
 
     @property
-    def full_text(self):
-        """
-        The full text to be shown. If it's longer than `max_characters` then
+    def full_text(self) -> str:
+        """The full text to be shown. If it's longer than ``max_characters`` then
         scrolling will occur as needed.
 
-        :return string: The full text of this label.
+        :return str: The full text of this label.
         """
         return self._full_text
 
     @full_text.setter
-    def full_text(self, new_text):
+    def full_text(self, new_text: str) -> None:
         if new_text[-1] != " ":
             new_text = "{} ".format(new_text)
         self._full_text = new_text

docs/api.rst

@@ -13,3 +13,6 @@
 
 .. automodule:: adafruit_display_text.bitmap_label
    :members:
+
+.. automodule:: adafruit_display_text.scrolling_label
+   :members:

docs/examples.rst

@@ -1,4 +1,4 @@
-Simple test
+Simple Test
 ------------
 
 Ensure your device works with this simple test.
@@ -7,7 +7,7 @@ Ensure your device works with this simple test.
     :caption: examples/display_text_simpletest.py
     :linenos:
 
-Bitmap_label Simple test
+Bitmap_label Simple Test
 ------------------------
 
 Simple test using bitmap_label to display text
@@ -16,6 +16,15 @@ Simple test using bitmap_label to display text
     :caption: examples/display_text_bitmap_label_simpletest.py
     :linenos:
 
+ScrollingLabel Simple Test
+---------------------------
+
+Simple test using scrolling_label to display text
+
+.. literalinclude:: ../examples/display_text_scrolling_label.py
+    :caption: examples/display_text_scrolling_label.py
+    :linenos:
+
 Label vs Bitmap_label Comparison
 --------------------------------
 
@@ -25,7 +34,7 @@ Example to compare Label and Bitmap_Label characteristics
     :caption: examples/display_text_label_vs_bitmap_label_comparison.py
     :linenos:
 
-Background color example
+Background Color Example
 ------------------------
 
 Show the text backgrounds features
@@ -34,7 +43,7 @@ Show the text backgrounds features
     :caption: examples/display_text_background_color.py
     :linenos:
 
-Text padding example
+Text Padding Example
 --------------------
 
 Show the text padding features in all directions
@@ -61,7 +70,7 @@ Boundingbox demonstration
     :caption: examples/display_text_textarea_boundingbox.py
     :linenos:
 
-Align Baseline example
+Align Baseline Example
 ----------------------
 
 Demonstrate how to align different labels to a common horizontal line
@@ -70,7 +79,7 @@ Demonstrate how to align different labels to a common horizontal line
     :caption: examples/display_text_label_align_baseline_comparison.py
     :linenos:
 
-Magtag example
+Magtag Example
 --------------
 
 Uses the MAGTAG to display some text
@@ -79,7 +88,7 @@ Uses the MAGTAG to display some text
     :caption: examples/display_text_magtag.py
     :linenos:
 
-MatrixPortal example
+MatrixPortal Example
 --------------------
 
 Uses the MatrixPortal to display some text
@@ -88,7 +97,7 @@ Uses the MatrixPortal to display some text
     :caption: examples/display_text_matrixportal.py
     :linenos:
 
-PyPortal example
+PyPortal Example
 ----------------
 
 Uses the Pyportal to display some text
@@ -97,7 +106,7 @@ Uses the Pyportal to display some text
     :caption: examples/display_text_pyportal.py
     :linenos:
 
-Wraptest example
+Wraptest Example
 ----------------
 
 Illustrates the wraptest feature

requirements.txt

@@ -3,5 +3,5 @@
 # SPDX-License-Identifier: Unlicense
 
 Adafruit-Blinka
-adafruit-blinka-displayio
+adafruit-blinka-displayio>=0.10.2
 adafruit-circuitpython-bitmap-font

setup.py

@@ -34,7 +34,7 @@
     author_email="[email protected]",
     install_requires=[
         "Adafruit-Blinka",
-        "adafruit-blinka-displayio",
+        "adafruit-blinka-displayio>=0.10.2",
         "adafruit-circuitpython-bitmap-font",
     ],
     # Choose your license