Merge pull request #161 from tekktrik/doc/update-typing

Update type hints

Author: FoamyGuy

adafruit_display_text/__init__.py

@@ -8,14 +8,21 @@
 """
 
 try:
-    from typing import List, Tuple
+    from typing import Optional, Union, List, Tuple
+    from fontio import BuiltinFont
+    from adafruit_bitmap_font.bdf import BDF
+    from adafruit_bitmap_font.pcf import PCF
 except ImportError:
     pass
 from displayio import Group, Palette
 
 
 def wrap_text_to_pixels(
-    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
+    string: str,
+    max_width: int,
+    font: Optional[Union[BuiltinFont, BDF, PCF]] = None,
+    indent0: str = "",
+    indent1: str = "",
 ) -> List[str]:
     # pylint: disable=too-many-branches, too-many-locals
 
@@ -27,7 +34,8 @@ def wrap_text_to_pixels(
 
     :param str string: The text to be wrapped.
     :param int max_width: The maximum number of pixels on a line before wrapping.
-    :param Font font: The font to use for measuring the text.
+    :param font: The font to use for measuring the text.
+    :type font: ~BuiltinFont, ~BDF, or ~PCF
     :param str indent0: Additional character(s) to add to the first line.
     :param str indent1: Additional character(s) to add to all other lines.
 
@@ -164,8 +172,9 @@ class LabelBase(Group):
     Subclasses should implement ``_set_text``, ``_set_font``, and ``_set_line_spacing`` to
     have the correct behavior for that type of label.
 
-    :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``.
+    :param font: A font class that has ``get_bounding_box`` and ``get_glyph``.
       Must include a capital M for measuring character size.
+    :type font: ~BuiltinFont, ~BDF, or ~PCF
     :param str text: Text to display
     :param int color: Color of all text in RGB hex
     :param int background_color: Color of the background, use `None` for transparent
@@ -192,7 +201,7 @@ class LabelBase(Group):
 
     def __init__(
         self,
-        font,
+        font: Union[BuiltinFont, BDF, PCF],
         x: int = 0,
         y: int = 0,
         text: str = "",
@@ -278,15 +287,15 @@ def _get_ascent_descent(self) -> Tuple[int, int]:
         return ascender_max, descender_max
 
     @property
-    def font(self) -> None:
+    def font(self) -> Union[BuiltinFont, BDF, PCF]:
         """Font to use for text display."""
         return self._font
 
-    def _set_font(self, new_font) -> None:
+    def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None:
         raise NotImplementedError("{} MUST override '_set_font'".format(type(self)))
 
     @font.setter
-    def font(self, new_font) -> None:
+    def font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None:
         self._set_font(new_font)
 
     @property
@@ -435,5 +444,5 @@ def label_direction(self, new_label_direction: str) -> None:
             raise RuntimeError("Please provide a valid text direction")
         self._set_label_direction(new_label_direction)
 
-    def _replace_tabs(self, text):
+    def _replace_tabs(self, text: str) -> str:
         return self._tab_text.join(text.split("\t"))

adafruit_display_text/bitmap_label.py

@@ -28,7 +28,10 @@
 
 
 try:
-    from typing import Tuple
+    from typing import Union, Optional, Tuple
+    from fontio import BuiltinFont
+    from adafruit_bitmap_font.bdf import BDF
+    from adafruit_bitmap_font.pcf import PCF
 except ImportError:
     pass
 
@@ -51,8 +54,9 @@ class Label(LabelBase):
     glyph (if its one line), or the (number of lines * linespacing + M)/2. That is,
     it will try to have it be center-left as close as possible.
 
-    :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``.
+    :param font: A font class that has ``get_bounding_box`` and ``get_glyph``.
       Must include a capital M for measuring character size.
+    :type font: ~BuiltinFont, ~BDF, or ~PCF
     :param str text: Text to display
     :param int color: Color of all text in RGB hex
     :param int background_color: Color of the background, use `None` for transparent
@@ -80,7 +84,9 @@ class Label(LabelBase):
      configurations possibles ``LTR``-Left-To-Right ``RTL``-Right-To-Left
      ``UPD``-Upside Down ``UPR``-Upwards ``DWR``-Downwards. It defaults to ``LTR``"""
 
-    def __init__(self, font, save_text=True, **kwargs) -> None:
+    def __init__(
+        self, font: Union[BuiltinFont, BDF, PCF], save_text: bool = True, **kwargs
+    ) -> None:
 
         self._bitmap = None
 
@@ -102,10 +108,10 @@ def __init__(self, font, save_text=True, **kwargs) -> None:
 
     def _reset_text(
         self,
-        font=None,
-        text: str = None,
-        line_spacing: float = None,
-        scale: int = None,
+        font: Optional[Union[BuiltinFont, BDF, PCF]] = None,
+        text: Optional[str] = None,
+        line_spacing: Optional[float] = None,
+        scale: Optional[int] = None,
     ) -> None:
         # pylint: disable=too-many-branches, too-many-statements
 
@@ -247,13 +253,15 @@ def _reset_text(
         self.anchored_position = self._anchored_position
 
     @staticmethod
-    def _line_spacing_ypixels(font, line_spacing: float) -> int:
+    def _line_spacing_ypixels(
+        font: Union[BuiltinFont, BDF, PCF], line_spacing: float
+    ) -> int:
         # Note: Scaling is provided at the Group level
         return_value = int(line_spacing * font.get_bounding_box()[1])
         return return_value
 
     def _text_bounding_box(
-        self, text: str, font
+        self, text: str, font: Union[BuiltinFont, BDF, PCF]
     ) -> Tuple[int, int, int, int, int, int]:
         # pylint: disable=too-many-locals
 
@@ -333,9 +341,9 @@ def _text_bounding_box(
 
     def _place_text(
         self,
-        bitmap,
+        bitmap: displayio.Bitmap,
         text: str,
-        font,
+        font: Union[BuiltinFont, BDF, PCF],
         xposition: int,
         yposition: int,
         skip_index: int = 0,  # set to None to write all pixels, other wise skip this palette index
@@ -432,10 +440,10 @@ def _place_text(
 
     def _blit(
         self,
-        bitmap,  # target bitmap
+        bitmap: displayio.Bitmap,  # target bitmap
         x: int,  # target x upper left corner
         y: int,  # target y upper left corner
-        source_bitmap,  # source bitmap
+        source_bitmap: displayio.Bitmap,  # source bitmap
         x_1: int = 0,  # source x start
         y_1: int = 0,  # source y start
         x_2: int = None,  # source x end
@@ -509,7 +517,7 @@ def _set_line_spacing(self, new_line_spacing: float) -> None:
         else:
             raise RuntimeError("line_spacing is immutable when save_text is False")
 
-    def _set_font(self, new_font) -> None:
+    def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None:
         self._font = new_font
         if self._save_text:
             self._reset_text(font=new_font, scale=self.scale)
@@ -519,7 +527,7 @@ def _set_font(self, new_font) -> None:
     def _set_text(self, new_text: str, scale: int) -> None:
         self._reset_text(text=self._replace_tabs(new_text), scale=self.scale)
 
-    def _set_background_color(self, new_color):
+    def _set_background_color(self, new_color: Optional[int]):
         self._background_color = new_color
         if new_color is not None:
             self._palette[0] = new_color
@@ -536,7 +544,7 @@ def _get_valid_label_directions(self) -> Tuple[str, ...]:
         return "LTR", "RTL", "UPD", "UPR", "DWR"
 
     @property
-    def bitmap(self):
+    def bitmap(self) -> displayio.Bitmap:
         """
         The Bitmap object that the text and background are drawn into.
 

adafruit_display_text/label.py

@@ -27,7 +27,10 @@
 
 
 try:
-    from typing import Tuple
+    from typing import Union, Optional, Tuple
+    from fontio import BuiltinFont
+    from adafruit_bitmap_font.bdf import BDF
+    from adafruit_bitmap_font.pcf import PCF
 except ImportError:
     pass
 
@@ -44,8 +47,9 @@ class Label(LabelBase):
     glyph (if its one line), or the (number of lines * linespacing + M)/2. That is,
     it will try to have it be center-left as close as possible.
 
-    :param Font font: A font class that has ``get_bounding_box`` and ``get_glyph``.
+    :param font: A font class that has ``get_bounding_box`` and ``get_glyph``.
       Must include a capital M for measuring character size.
+    :type font: ~BuiltinFont, ~BDF, or ~PCF
     :param str text: Text to display
     :param int color: Color of all text in RGB hex
     :param int background_color: Color of the background, use `None` for transparent
@@ -79,7 +83,7 @@ class Label(LabelBase):
      configurations possibles ``LTR``-Left-To-Right ``RTL``-Right-To-Left
      ``TTB``-Top-To-Bottom ``UPR``-Upwards ``DWR``-Downwards. It defaults to ``LTR``"""
 
-    def __init__(self, font, **kwargs) -> None:
+    def __init__(self, font: Union[BuiltinFont, BDF, PCF], **kwargs) -> None:
         self._background_palette = Palette(1)
         self._added_background_tilegrid = False
 
@@ -166,9 +170,11 @@ def _create_background_box(self, lines: int, y_offset: int) -> TileGrid:
 
         return tile_grid
 
-    def _set_background_color(self, new_color: int) -> None:
+    def _set_background_color(self, new_color: Optional[int]) -> None:
         """Private class function that allows updating the font box background color
-        :param int new_color: color as an RGB hex number."""
+
+        :param int new_color: Color as an RGB hex number, setting to None makes it transparent
+        """
 
         if new_color is None:
             self._background_palette.make_transparent(0)
@@ -397,7 +403,7 @@ def _reset_text(self, new_text: str) -> None:
         self._update_text(str(self._replace_tabs(new_text)))
         self.anchored_position = current_anchored_position
 
-    def _set_font(self, new_font) -> None:
+    def _set_font(self, new_font: Union[BuiltinFont, BDF, PCF]) -> None:
         old_text = self._text
         current_anchored_position = self.anchored_position
         self._text = ""

docs/conf.py

@@ -25,7 +25,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-autodoc_mock_imports = ["displayio"]
+autodoc_mock_imports = ["displayio", "adafruit_bitmap_font"]
 
 
 intersphinx_mapping = {