From: James Carr <lesamouraipourpre@gmail.com>
Date: Mon, 16 Aug 2021 12:33:46 +0000 (+0100)
Subject: Prepare for the removal of the max_size parameter from displayio.Group - see #67
X-Git-Tag: 0.7.0~1^2
X-Git-Url: https://git.ayoreis.com/hackapet/Adafruit_Blinka_Displayio.git/commitdiff_plain/6e2e96674a45b2939fa6e6614f4e75e43c552b64

Prepare for the removal of the max_size parameter from displayio.Group - see #67
The parameter is still allowed but will print a deprecation warning.

The documentation now builds entries for the classes within displayio.
---

diff --git a/displayio/display.py b/displayio/display.py
index c0781cf..4d5a8ba 100644
--- a/displayio/display.py
+++ b/displayio/display.py
@@ -44,14 +44,6 @@ class Display:
 
     Most people should not use this class directly. Use a specific display driver instead
     that will contain the initialization sequence at minimum.
-
-    .. class::
-        Display(display_bus, init_sequence, *, width, height, colstart=0, rowstart=0, rotation=0,
-        color_depth=16, grayscale=False, pixels_in_byte_share_row=True, bytes_per_cell=1,
-        reverse_pixels_in_byte=False, set_column_command=0x2a, set_row_command=0x2b,
-        write_ram_command=0x2c, set_vertical_scroll=0, backlight_pin=None, brightness_command=None,
-        brightness=1.0, auto_brightness=False, single_byte_bounds=False, data_as_commands=False,
-        auto_refresh=True, native_frames_per_second=60)
     """
 
     def __init__(
@@ -93,16 +85,18 @@ class Display:
         excluding any delay byte. The third through final bytes are the remaining command
         parameters. The next byte will begin a new command definition. Here is a portion of
         ILI9341 init code:
+
         .. code-block:: python
 
             init_sequence = (
-                b"\xe1\x0f\x00\x0E\x14\x03\x11\x07\x31\xC1\x48\x08\x0F\x0C\x31\x36\x0F"
-                b"\x11\x80\x78"# Exit Sleep then delay 0x78 (120ms)
-                b"\x29\x80\x78"# Display on then delay 0x78 (120ms)
+                b"\\xE1\\x0F\\x00\\x0E\\x14\\x03\\x11\\x07\\x31\
+\\xC1\\x48\\x08\\x0F\\x0C\\x31\\x36\\x0F"
+                b"\\x11\\x80\\x78"  # Exit Sleep then delay 0x78 (120ms)
+                b"\\x29\\x80\\x78"  # Display on then delay 0x78 (120ms)
             )
             display = displayio.Display(display_bus, init_sequence, width=320, height=240)
 
-        The first command is 0xe1 with 15 (0xf) parameters following. The second and third
+        The first command is 0xE1 with 15 (0x0F) parameters following. The second and third
         are 0x11 and 0x29 respectively with delays (0x80) of 120ms (0x78) and no parameters.
         Multiple byte literals (b”“) are merged together on load. The parens are needed to
         allow byte literals on subsequent lines.
diff --git a/displayio/group.py b/displayio/group.py
index e6deba8..e84a487 100644
--- a/displayio/group.py
+++ b/displayio/group.py
@@ -28,16 +28,28 @@ Transform = recordclass("Transform", "x y dx dy scale transpose_xy mirror_x mirr
 
 
 class Group:
-    """Manage a group of sprites and groups and how they are inter-related."""
+    """
+    Manage a group of sprites and groups and how they are inter-related.
 
-    def __init__(self, *, max_size=4, scale=1, x=0, y=0):
-        """Create a Group of a given size and scale. Scale is in
-        one dimension. For example, scale=2 leads to a layer’s
-        pixel being 2x2 pixels when in the group.
+    Create a Group of a given scale. Scale is in one dimension. For example, scale=2
+    leads to a layer's pixel being 2x2 pixels when in the group.
+    """
+
+    def __init__(self, *, max_size=None, scale=1, x=0, y=0):
+        """
+        :param Optional(int) max_size: *DEPRECATED* This has been removed in CircuitPython 7 and
+            will be removed in a future version of ``Adafruit_Blinka_Displayio``
+        :param int scale: Scale of layer pixels in one dimension.
+        :param int x: Initial x position within the parent.
+        :param int y: Initial y position within the parent.
         """
-        if not isinstance(max_size, int) or max_size < 1:
-            raise ValueError("Max Size must be >= 1")
-        self._max_size = max_size
+
+        if max_size is not None:
+            print(
+                "The max_size parameter displayio.Group() has been deprecated. "
+                "Please remove max_size from your code."
+            )
+
         if not isinstance(scale, int) or scale < 1:
             raise ValueError("Scale must be >= 1")
         self._scale = 1  # Use the setter below to actually set the scale
@@ -93,8 +105,6 @@ class Group:
             raise ValueError("Invalid Group Member")
         if layer.in_group:
             raise ValueError("Layer already in a group.")
-        if len(self._layers) == self._max_size:
-            raise RuntimeError("Group full")
         self._layers.insert(index, layer)
         self._layer_update(index)
 
diff --git a/docs/api.rst b/docs/api.rst
index 2fa7117..0bfc8e6 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -4,11 +4,13 @@
 .. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
 .. use this format as the module name: "adafruit_foo.foo"
 
+
 .. automodule:: displayio
-   :members:
+    :members: Bitmap, ColorConverter, Display, EPaperDisplay, FourWire, Group, I2CDisplay,
+        OnDiskBitmap, Palette, ParallelBus, Shape, TileGrid
 
 .. automodule:: fontio
-   :members:
+    :members:
 
 .. automodule:: terminalio
-   :members:
+    :members:
diff --git a/docs/conf.py b/docs/conf.py
index 8ab22c0..02e8c13 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -81,6 +81,9 @@ default_role = "any"
 #
 add_function_parentheses = True
 
+# Generate the class documentation from both the class docstring and the __init__ docstring
+autoclass_content = "both"
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"