Add Support for Multiple Screens (#47)

* Add multi-screens option

* Add tests for new methods

* Bump Pytest to 8.3.5

* Drop support for Python 3.7, 3.8

* Add support for Python 3.10, 3.11, 3.12, 3.13

Author: ShaneSutro

.travis.yml

@@ -5,12 +5,14 @@ dist: focal
 
 language: python
 python:
-  - '3.7'
-  - '3.8'
   - '3.9'
+  - '3.10'
+  - '3.11'
+  - '3.12'
+  - '3.13'
 
 install:
-  - pip install setuptools==60.8.2
+  - pip install setuptools==80.3.1
   - pip install -r requirements.txt
   - pip install .
 
@@ -23,5 +25,5 @@ deploy:
   skip_existing: true
   edge: true
   on:
-    python: 3.9
+    python: 3.13
     tags: true

requirements.txt

@@ -1,2 +1,2 @@
-pytest==7.0.0
+pytest==8.3.5
 requests==2.32.3

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="Vestaboard",
-    version="1.2.4",
+    version="2.0.0",
     author="Shane Sutro",
     author_email="shane@shanesutro.com",
     description="A Vestaboard Wrapper",
@@ -14,15 +14,13 @@
     url="https://github.com/ShaneSutro/Vestaboard.git",
     packages=setuptools.find_packages(),
     license="MIT",
-    install_requires=[
-        'requests'
-    ],
+    install_requires=["requests"],
     classifiers=[
         "Programming Language :: Python :: 3 :: Only",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",
     ],
-    python_requires='>=3.6',
-)
+    python_requires=">=3.9",
+)

tests/test_formatting.py

@@ -210,4 +210,11 @@ def test_convert_with_vestaboard_formatting():
     # fmt: on
 
     assert t1 == e1
-    assert t2 == e2
+    assert t2 == e2
+
+def test_create_screens_function():
+    t1 = Formatter().createScreens("Let us go forth, the tellers of tales, and seize whatever prey the heart long for, and have no fear. - W.B. Yeats, in his finest hour of lucidity")
+
+    assert len(t1) == 2
+    assert len(t1[0]) == 6
+    assert len(t1[1]) == 6

tests/test_init.py

@@ -217,6 +217,14 @@ def test_large_board():
         assert large_board == expected
 
 
+def test_multi_screens():
+    # fmt: off
+    multiScreens = [[[12, 5, 20, 0, 21, 19, 0, 7, 15, 0, 6, 15, 18, 20, 8, 55, 0, 20, 8, 5, 0, 0], [20, 5, 12, 12, 5, 18, 19, 0, 15, 6, 0, 20, 1, 12, 5, 19, 55, 0, 1, 14, 4, 0], [19, 5, 9, 26, 5, 0, 23, 8, 1, 20, 5, 22, 5, 18, 0, 16, 18, 5, 25, 0, 0, 0], [20, 8, 5, 0, 8, 5, 1, 18, 20, 0, 12, 15, 14, 7, 0, 6, 15, 18, 55, 0, 0, 0], [1, 14, 4, 0, 8, 1, 22, 5, 0, 14, 15, 0, 6, 5, 1, 18, 56, 0, 44, 0, 0, 0], [23, 56, 2, 56, 0, 25, 5, 1, 20, 19, 55, 0, 9, 14, 0, 8, 9, 19, 0, 0, 0, 0]], [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [6, 9, 14, 5, 19, 20, 0, 8, 15, 21, 18, 0, 15, 6, 0, 0, 0, 0, 0, 0, 0, 0], [12, 21, 3, 9, 4, 9, 20, 25, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]]
+    # fmt: on
+    vb = create_fake_vestaboard()
+    vb.sendScreens(multiScreens, 1)
+
+
 def create_fake_vestaboard():
     i = vestaboard.Installable(
         apiKey=TEST_API_KEY,

vestaboard/__init__.py

@@ -9,6 +9,8 @@
 import warnings
 import json
 import requests
+import threading
+import time
 from vestaboard.formatter import Formatter
 import vestaboard.vbUrls as vbUrls
 
@@ -213,7 +215,10 @@ def raw(self, charList: list, pad=None):
         if self.localKey and self.localIP:
             self._raw_local(finalText["characters"])
         elif self.readWrite and self.apiKey:
-            headers = {"X-Vestaboard-Read-Write-Key": self.apiKey, "Content-Type": "application/json"}
+            headers = {
+                "X-Vestaboard-Read-Write-Key": self.apiKey,
+                "Content-Type": "application/json",
+            }
             requests.post(
                 vbUrls.readWrite,
                 headers=headers,
@@ -359,6 +364,74 @@ def _raw_local(self, chars):
         )
         res.raise_for_status()
 
+    def _sendScreensNonBlocking(self, screens, delay):
+        for screenIndex in range(len(screens)):
+            screen = screens[screenIndex]
+            isLastScreen = screenIndex == len(screens) - 1
+            for i, row in enumerate(screen):
+                if not isinstance(row, list):
+                    raise ValueError(f"Nested items must be lists, not {type(row)}.")
+                if len(row) != 22:
+                    raise ValueError(
+                        f"Nested lists must be exactly 22 characters long. Element at {i} is {len(row)} characters long. Use the Formatter().convertLine() function if you need to add padding to your row."
+                    )
+                for j, char in enumerate(row):
+                    if not isinstance(char, int):
+                        raise ValueError(
+                            f"Nested lists must contain numbers only - check row {i} char {j} (0 indexed)"
+                        )
+            if len(screen) > 6:
+                # warnings.warn doesn't work with f strings
+                warning_message = f"The Vestaboard API accepts only 6 lines of characters; you've passed in {len(screen)}. Only the first 6 will be shown."
+                warnings.warn(warning_message)
+                del screen[6:]
+
+            finalText = Formatter()._raw(screen)
+            print(f"Sending screen {screenIndex + 1} of {len(screens)}")
+            if self.localKey and self.localIP:
+                self._raw_local(finalText["characters"])
+            elif self.readWrite and self.apiKey:
+                headers = {
+                    "X-Vestaboard-Read-Write-Key": self.apiKey,
+                    "Content-Type": "application/json",
+                }
+                requests.post(
+                    vbUrls.readWrite,
+                    headers=headers,
+                    data=json.dumps(finalText["characters"]),
+                    timeout=5,
+                )
+            else:
+                headers = {
+                    "X-Vestaboard-Api-Key": self.apiKey,
+                    "X-Vestaboard-Api-Secret": self.apiSecret,
+                }
+                requests.post(
+                    vbUrls.post.format(self.subscriptionId),
+                    headers=headers,
+                    json=finalText,
+                    timeout=5,
+                )
+            if not isLastScreen:
+                time.sleep(delay)
+
+    def sendScreens(self, screens, delay=60):
+        """
+        Posts already-formatted screens to the board with a pre-set delay.
+        Intended to be used with the Formatter.createScreens method. This method
+        expects each screen to be a fully-sized list of lists.
+
+        Keyword arguments:
+
+        `screens` - a list of screens
+
+        `delay` - seconds to delay between screens. Defaults to 60 seconds.
+        """
+        thread = threading.Thread(
+            target=self._sendScreensNonBlocking, args=(screens, delay)
+        )
+        thread.start()
+
 
 class Installable:
     def __init__(

vestaboard/formatter.py

@@ -230,3 +230,62 @@ def convertPlainText(
                         convertedLines.insert(0, blankLine)
 
         return convertedLines[0:maxRows]
+
+    def createScreens(
+        self,
+        text,
+        size=None,
+        justify="center",
+        align="center",
+        useVestaboardCentering=False,
+    ):
+        """
+        This function returns multiple screens of text. This is particularly useful when the
+        desired text is too big to fit on a single screen. The output is similar to the
+        Formatter.convertPlainText method; the primary difference is the return shape, which
+        is a nested list of lists.
+
+        The returned list size will match the `size` passed in and defaults to [6, 22].
+        """
+        if size is None:
+            size = [6, 22]
+        maxRows, maxCols = size
+        splitLines = []
+        for linebreak in text.split("\n"):
+            splitLines += textwrap.fill(linebreak, maxCols).split("\n")
+
+        convertedLines = []
+
+        if useVestaboardCentering:
+            if justify == "center":
+                warnings.warn(
+                    "Vestaboard formatting only affects left or right-justified text. Because of this, your text will be left justified by default. If you don't want your text left justified, remove `useVestaboardCentering` from your function call."
+                )
+                convertedLines = self._add_vestaboard_spacing(splitLines, size)
+            else:
+                convertedLines = self._add_vestaboard_spacing(splitLines, size, justify)
+        else:
+            for line in splitLines:
+                convertedLines.append(self.convertLine(line, justify, "black", False))
+
+        screens = [
+            convertedLines[i : i + maxRows]
+            for i in range(0, len(convertedLines), maxRows)
+        ]
+
+        for screen in screens:
+            if len(screen) < maxRows:
+                blankLine = [0] * maxCols
+                while len(screen) < maxRows:
+                    if align == "bottom":
+                        screen.insert(0, blankLine)
+                    else:
+                        screen.append(blankLine)
+
+                    if len(screen) < maxRows:
+                        if align == "top":
+                            screen.append(blankLine)
+                        else:
+                            screen.insert(0, blankLine)
+
+        return screens