add copyright MIT license

Author: Matt Land

adafruit_imageload/tests/__init__.py

@@ -0,0 +1,34 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Matt Land
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_imageload.tests.test_bmp_indexed_load`
+====================================================
+
+* Author(s):  Matt Land
+
+This is the location for tests.
+Small example image files can be placed in examples/images,
+and tests written to load them go in this module.
+
+See also: docs/developing.rst
+
+"""

adafruit_imageload/tests/displayio_shared_bindings.py

@@ -1,4 +1,28 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Matt Land
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 """
+`adafruit_imageload.tests.displayio_shared_bindings`
+====================================================
+
 The classes in this file are designed to emulate Circuitpython's displayio classes
 for Bitmap and Palette. These mimic classes should have the same methods and interface as the real interface,
 but with extra validation checks, warnings, and messages to facilitate debugging.
@@ -7,15 +31,20 @@
  working correctly on hardware running Circuitpython, but without needing to upload code to a board
  after each attempt.
 
+* Author(s):  Matt Land
+
 """
+from typing import Union
 
 
 class Bitmap_C_Interface(object):
     """
-    Simulates the displayio.Bitmap class for testing
+    A class to simulate the displayio.Bitmap class for testing, based on
+    https://circuitpython.readthedocs.io/en/latest/shared-bindings/displayio/Bitmap.html
+    In case of discrepancy, the C implementation takes precedence.
     """
 
-    def __init__(self, width, height, colors):
+    def __init__(self, width: int, height: int, colors: int) -> None:
         self.width = width
         self.height = height
         self.colors = colors
@@ -31,9 +60,15 @@ def _abs_pos(self, width: int, height: int) -> int:
     def _decode(self, position: int) -> tuple:
         return position % self.width, position // self.width
 
-    def __setitem__(self, key: tuple, value: int):
+    def __setitem__(self, key: Union[tuple, int], value: int) -> None:
+        """
+        Set using x, y coordinates, or absolution position
+        bitmap[0] = 1
+        bitmap[2,1] = 5
+        """
         if isinstance(key, tuple):
-            # order is X, Y from the docs https://github.com/adafruit/circuitpython/blob/master/shared-bindings/displayio/Bitmap.c
+            # order is X, Y from the docs
+            # https://github.com/adafruit/circuitpython/blob/master/shared-bindings/displayio/Bitmap.c
             self.__setitem__(self._abs_pos(key[0], key[1]), value)
             return
         if not isinstance(value, (int)):
@@ -42,7 +77,7 @@ def __setitem__(self, key: tuple, value: int):
             raise ValueError(f"pixel value {value} too large")
         self.data[key] = value
 
-    def __getitem__(self, item: tuple) -> bytearray:
+    def __getitem__(self, item: Union[tuple, int]) -> bytearray:
         if isinstance(item, tuple):
             return self.__getitem__(self._abs_pos(item[0], item[1]))
         if item > self.height * self.width:
@@ -52,7 +87,11 @@ def __getitem__(self, item: tuple) -> bytearray:
         except KeyError:
             raise RuntimeError("no data at {} [{}]".format(self._decode(item), item))
 
-    def validate(self):
+    def validate(self) -> None:
+        """
+        method to to make sure all pixels allocated in the Bitmap
+        were set with a value
+        """
         if not self.data:
             raise ValueError("no rows were set / no data in memory")
         for i in range(self.height * self.width, 0):
@@ -61,7 +100,18 @@ def validate(self):
             except KeyError:
                 raise ValueError("missing data at {i}")
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """
+        method to dump the contents of the Bitmap to a terminal,
+        for debugging purposes
+
+        Example:
+        --------
+
+        bitmap = Bitmap(5, 4, 4)
+        ...  # assign bitmap values
+        print(str(bitmap))
+        """
         out = "\n"
         for y in range(self.height):
             for x in range(self.width):
@@ -73,29 +123,41 @@ def __str__(self):
 
 class Palette_C_Interface(object):
     """
-    Simulates the displayio.Palette class for testing
+    A class to simulates the displayio.Palette class for testing, based on
+    https://circuitpython.readthedocs.io/en/latest/shared-bindings/displayio/Palette.html
+    In case of discrepancy, the C implementation takes precedence.
     """
 
-    def __init__(self, num_colors):
+    def __init__(self, num_colors: int) -> None:
         self.num_colors = num_colors
         self.colors = {}
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: int, value: Union[bytes, int, bytearray]) -> None:
+        """
+        Set using zero indexed color value
+        palette = Palette(1)
+        palette[0] = 0xFFFFFF
+
+        """
         if key >= self.num_colors:
             raise ValueError(
                 f"palette index {key} is greater than allowed by num_colors {self.num_colors}"
             )
-        if not isinstance(value, (bytes, int)):
+        if not isinstance(value, (bytes, int, bytearray)):
             raise ValueError(f"palette color should be bytes, not {type(value)}")
-        if isinstance(value, int) and value > 255:
+        if isinstance(value, int) and value > 0xFFFFFF:
             raise ValueError(f"palette color int {value} is too large")
         if self.colors.get(key):
             raise ValueError(
                 f"palette color {key} was already set, should not reassign"
             )
         self.colors[key] = value
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: int) -> Union[bytes, int, bytearray]:
+        """
+        Warning: this method is not supported in the actual C interface.
+        It is provided here for debugging purposes.
+        """
         if item >= self.num_colors:
             raise ValueError(
                 f"palette index {item} should be less than {self.num_colors}"
@@ -105,17 +167,35 @@ def __getitem__(self, item):
         return self.colors[item]
 
     def validate(self):
+        """
+        method to make sure all colors allocated in Palette were set to a value
+        """
         if not self.colors:
-            raise ValueError("no palette colors were set")
-        if len(self.colors) > self.num_colors:
-            raise ValueError("too many colors inserted into palette")
+            raise IndexError("no palette colors were set")
+        if len(self.colors) != self.num_colors:
+            raise IndexError(
+                "palette was initialized for {} colors, but only {} were inserted".format(
+                    self.num_colors, len(self.colors)
+                )
+            )
         for i in range(self.num_colors):
             try:
                 self.colors
             except IndexError:
                 raise ValueError("missing color `{}` in palette color list".format(i))
 
     def __str__(self):
+        """
+        method to dump the contents of the Palette to a terminal,
+        for debugging purposes
+
+        Example:
+        --------
+
+        palette = Palette(1)
+        palette[0] = 0xFFFFFF
+        print(str(palette))
+        """
         out = "\nPalette:\n"
         for y in range(len(self.colors)):
             out += f" [{y}] {self.colors[y]}\n"

adafruit_imageload/tests/test_bitmap_c_interface.py

@@ -1,3 +1,33 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Matt Land
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_imageload.tests.test_bitmap_c_interface`
+====================================================
+
+These tests are to validate the displayio_shared_bindings classes that other tests are built on.
+
+* Author(s):  Matt Land
+
+"""
 from unittest import TestCase
 from .displayio_shared_bindings import Bitmap_C_Interface
 

adafruit_imageload/tests/test_bmp_indexed_load.py

@@ -1,6 +1,35 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Matt Land
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_imageload.tests.test_bmp_indexed_load`
+====================================================
+
+* Author(s):  Matt Land
+
+"""
+
 import os
 from unittest import TestCase
-from adafruit_imageload import load
+from .. import load
 from .displayio_shared_bindings import Bitmap_C_Interface, Palette_C_Interface
 
 
@@ -27,6 +56,6 @@ def test_order_bgra_to_rgba(self):
         self.assertEqual(16, palette.num_colors)
         palette.validate()
         # make sure bye order swapped
-        self.assertTrue(palette[4] in [b'\x9d\x00\xff\x00', b'\x9d\x00\xff'])
+        self.assertTrue(palette[4] in [b"\x9d\x00\xff\x00", b"\x9d\x00\xff"])
         # uncomment line below to see a string representation of the object
-        #self.fail(str(palette))
+        # self.fail(str(palette))