IS-Matrix-Forge 1.0.0.dev8__tar.gz → 1.0.0.dev27__tar.gz

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: IS-Matrix-Forge
-Version: 1.0.0.dev8
+Version: 1.0.0.dev27
 Summary: 
 License: MIT
 Keywords: led,matrix,framework,hardware
@@ -19,12 +19,16 @@ Requires-Dist: easy-exit-calls (>=1.0.0.dev1,<2.0.0)
 Requires-Dist: imapclient (==3.0.1)
 Requires-Dist: inspy-logger (>=3.2.3,<4.0.0)
 Requires-Dist: inspyre-toolbox (>=1.6.0.dev23)
+Requires-Dist: ipywidgets (==8.1.7)
+Requires-Dist: notebook (>=7.4.4,<8.0.0)
 Requires-Dist: opencv-python (>=4.11.0.86,<5.0.0.0)
 Requires-Dist: pillow (>=11.2.1,<12.0.0)
+Requires-Dist: psutil (==6.1.1)
 Requires-Dist: pyserial (>=3.5,<4.0)
 Requires-Dist: pysimplegui-4-foss (==4.60.4.1)
 Requires-Dist: pysimpleguiweb (==0.39.0)
 Requires-Dist: requests (>=2.32.4,<3.0.0)
+Requires-Dist: wmi (>=1.5.1,<2.0.0) ; sys_platform == "win32"
 Project-URL: Homepage, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Project-URL: Repository, https://github.com/Inspyre-Softworks/IS-Matrix-Forge
 Description-Content-Type: text/markdown
@@ -132,6 +136,26 @@ ctrl = LEDMatrixController(DEVICES[0])
 ctrl.scroll_text("Hello World!", loop=False)
 ```
 
+## Controller Architecture
+
+- Composition is implemented via multiple mixins that all use cooperative
+  initialization with `super()`.
+- MRO ordering ensures safe access patterns during `__init__`:
+  - `DeviceBase` initializes early so mixins can use `self.device`.
+  - `BrightnessManager` precedes `BreatherManager` because the breather inspects
+    brightness at init time.
+  - `BreatherManager` precedes `IdentifyManager` because `IdentifyManager` may
+    call `@synchronized` methods in `__init__` that rely on a breather pause context.
+  - `Loggable` is placed last so the cooperative chain can pass `logger=` safely.
+- Thread safety: pass `thread_safe=True` to enable an internal `RLock` used by
+  the `@synchronized` decorator for device operations.
+- Logging: integrates with InspyLogger when available and falls back to a simple
+  logger; the controller passes `parent_log_device` through the cooperative chain
+  and the fallback stub supports it.
+
+MRO diagram (left → right, init order)
+`DeviceBase → KeepAliveManager → AnimationManager → DrawingManager → BrightnessManager → BreatherManager → IdentifyManager → Loggable`
+
 ### Progress Bars
 
 ```python
@@ -184,6 +208,19 @@ run_power_monitor(device)
 Contributions are welcome! If you have ideas or improvements for Matrix Forge,
 feel free to open an issue or submit a pull request.
 
+- See docs/contributing-mixins.md for guidance on authoring new controller mixins
+  using cooperative initialization and the `@synchronized` decorator.
+  A minimal reference mixin is available at
+  `is_matrix_forge/led_matrix/controller/components/example_template.py`.
+
+Quick checklist for a new controller mixin
+- Create `is_matrix_forge/led_matrix/controller/components/<name>.py` with `ClassNameManager`.
+- In `__init__(...)`, accept keyword-only args and call `super().__init__(**kwargs)`.
+- Avoid IO-heavy work in `__init__`; use `@synchronized` for device methods.
+- If calling synchronized methods in `__init__`, ensure MRO places you after `BreatherManager`.
+- If adding to the main controller, place after `DeviceBase` and before `IdentifyManager`; consider dependencies.
+- Provide docstrings, type hints, and a small usage example or test.
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE.md file for details.

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev27}/README.md

@@ -80,7 +80,7 @@ This project requires Python 3.12 or newer and the following dependencies:
    pip install .
    ```
 
-## Usage Examples
+## Usage Examples
 
 ### Identify Connected Devices
 
@@ -98,8 +98,28 @@ from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
 from is_matrix_forge.led_matrix.helpers.device import DEVICES
 
 ctrl = LEDMatrixController(DEVICES[0])
-ctrl.scroll_text("Hello World!", loop=False)
-```
+ctrl.scroll_text("Hello World!", loop=False)
+```
+
+## Controller Architecture
+
+- Composition is implemented via multiple mixins that all use cooperative
+  initialization with `super()`.
+- MRO ordering ensures safe access patterns during `__init__`:
+  - `DeviceBase` initializes early so mixins can use `self.device`.
+  - `BrightnessManager` precedes `BreatherManager` because the breather inspects
+    brightness at init time.
+  - `BreatherManager` precedes `IdentifyManager` because `IdentifyManager` may
+    call `@synchronized` methods in `__init__` that rely on a breather pause context.
+  - `Loggable` is placed last so the cooperative chain can pass `logger=` safely.
+- Thread safety: pass `thread_safe=True` to enable an internal `RLock` used by
+  the `@synchronized` decorator for device operations.
+- Logging: integrates with InspyLogger when available and falls back to a simple
+  logger; the controller passes `parent_log_device` through the cooperative chain
+  and the fallback stub supports it.
+
+MRO diagram (left → right, init order)
+`DeviceBase → KeepAliveManager → AnimationManager → DrawingManager → BrightnessManager → BreatherManager → IdentifyManager → Loggable`
 
 ### Progress Bars
 
@@ -148,10 +168,23 @@ run_power_monitor(device)
 2. Check that the matrix dimensions match the expected 9x34 size.
 3. Try clearing the matrix and restarting the application.
 
-## Contributing
-
-Contributions are welcome! If you have ideas or improvements for Matrix Forge,
-feel free to open an issue or submit a pull request.
+## Contributing
+
+Contributions are welcome! If you have ideas or improvements for Matrix Forge,
+feel free to open an issue or submit a pull request.
+
+- See docs/contributing-mixins.md for guidance on authoring new controller mixins
+  using cooperative initialization and the `@synchronized` decorator.
+  A minimal reference mixin is available at
+  `is_matrix_forge/led_matrix/controller/components/example_template.py`.
+
+Quick checklist for a new controller mixin
+- Create `is_matrix_forge/led_matrix/controller/components/<name>.py` with `ClassNameManager`.
+- In `__init__(...)`, accept keyword-only args and call `super().__init__(**kwargs)`.
+- Avoid IO-heavy work in `__init__`; use `@synchronized` for device methods.
+- If calling synchronized methods in `__init__`, ensure MRO places you after `BreatherManager`.
+- If adding to the main controller, place after `DeviceBase` and before `IdentifyManager`; consider dependencies.
+- Provide docstrings, type hints, and a small usage example or test.
 
 ## License
 

is_matrix_forge-1.0.0.dev27/is_matrix_forge/Untitled.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "a6d553a0-fca1-411a-a7bd-cf15dce52e97",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "a9c234aa78a641018ba78e54e9a3755b",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(Dropdown(description='Pick a pattern to render...', options=('All LEDs on', 'Gradient (0-13% Br…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from is_matrix_forge.led_matrix import get_controllers\n",
+    "import ipywidgets as widgets\n",
+    "CONTROLLERS = get_controllers(threaded = True)\n",
+    "PATTERNS = CONTROLLERS[0].built_in_pattern_names\n",
+    "\n",
+    "\n",
+    "class DropdownWithButton:\n",
+    "    def __init__(self, options, description='Choose:', button_desc='Run', callback=None):\n",
+    "        self.output = widgets.Output()\n",
+    "        self.dropdown = widgets.Dropdown(\n",
+    "            options=options, description=description, disabled=False\n",
+    "        )\n",
+    "        self.button = widgets.Button(\n",
+    "            description=button_desc, disabled=True, button_style='primary'\n",
+    "        )\n",
+    "        self.callback = callback or self.default_callback\n",
+    "\n",
+    "        # Set up observers\n",
+    "        self.dropdown.observe(self._on_select, names='value')\n",
+    "        self.button.on_click(self._on_click)\n",
+    "\n",
+    "        # Layout\n",
+    "        self.container = widgets.VBox([self.dropdown, self.button, self.output])\n",
+    "        display(self.container)\n",
+    "\n",
+    "    def _on_select(self, change):\n",
+    "        self.button.disabled = False  # Enable button once a selection is made\n",
+    "\n",
+    "    def _on_click(self, b):\n",
+    "        with self.output:\n",
+    "            # Clear prior output\n",
+    "            self.output.clear_output()\n",
+    "            self.callback(self.dropdown.value)\n",
+    "\n",
+    "    @staticmethod\n",
+    "    def default_callback(value):\n",
+    "        print(f\"You selected: {value}\")\n",
+    "\n",
+    "\n",
+    "\n",
+    "def render(selection):\n",
+    "    CONTROLLERS[0].draw_pattern(selection)\n",
+    "\n",
+    "\n",
+    "\n",
+    "drp_bttn = DropdownWithButton(\n",
+    "    options=PATTERNS,\n",
+    "    description='Pick a pattern to render...',\n",
+    "    button_desc='Render',\n",
+    "    callback=render\n",
+    "\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8533a241-ef3b-4a44-99cd-2e88cabb9fbb",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

is_matrix_forge-1.0.0.dev27/is_matrix_forge/__init__.py

@@ -0,0 +1 @@
+from is_matrix_forge.led_matrix.controller import get_controllers

{is_matrix_forge-1.0.0.dev8 → is_matrix_forge-1.0.0.dev27}/is_matrix_forge/assets/__init__.py

@@ -3,6 +3,6 @@ Author: Taylor B. tayjaybabee@gmail.com
 Date: 2025-04-15 09:15:37
 LastEditors: Taylor B. tayjaybabee@gmail.com
 LastEditTime: 2025-04-15 09:24:40
-FilePath: is_matrix_forge/assets/grid.py
+FilePath: is_matrix_forge/assets/base.py
 Description: 这是默认设置,可以在设置》工具》File Description中进行配置
 """

is_matrix_forge-1.0.0.dev27/is_matrix_forge/assets/digit_map.py

@@ -0,0 +1,82 @@
+"""
+Contains the pixel representation of the ld states within a 3x5 grid.
+"""
+
+
+DIGITS = {
+    "0": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "1": [
+        [0, 1, 0],
+        [1, 1, 0],
+        [0, 1, 0],
+        [0, 1, 0],
+        [1, 1, 1],
+    ],
+    "2": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+    ],
+    "3": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+    "4": [
+        [1, 0, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+    ],
+    "5": [
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+    "6": [
+        [1, 1, 1],
+        [1, 0, 0],
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "7": [
+        [1, 1, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+        [0, 0, 1],
+    ],
+    "8": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+    ],
+    "9": [
+        [1, 1, 1],
+        [1, 0, 1],
+        [1, 1, 1],
+        [0, 0, 1],
+        [1, 1, 1],
+    ],
+}
+
+
+__all__ = [
+    'DIGITS'
+]

is_matrix_forge-1.0.0.dev27/is_matrix_forge/assets/font_map/base.py

@@ -0,0 +1,289 @@
+"""
+Author:
+    Inspyre Softworks
+
+Project:
+    IS-Matrix-Forge
+
+File:
+    ${DIR_PATH}/${FILE_NAME}
+
+Description:
+    FontMap: a dict-like facade over character/symbol glyph data with optional
+    case-insensitive lookups and a configurable fallback character.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Iterator
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Optional, Tuple, Callable
+
+from inspyre_toolbox.syntactic_sweets.classes import validate_type
+from .models.glyph import Glyph
+from .helpers import load_builtin_char_map, get_ignore_case, has_key_ignore_case
+
+
+@dataclass(init=False, slots=True)
+class FontMap(Mapping[str, Glyph]):
+    """
+    FontMap allows lookup of character and symbol patterns as a dict-like mapping.
+
+    Parameters:
+        font_map:
+            Either:
+              - a *combined* map: { 'A': Glyph, '?': Glyph, ... }, or
+              - a *raw* map with top-level keys for characters/symbols:
+                { 'characters': {...}, 'symbols': {...} }.
+            If None, falls back to `load_builtin_char_map()`.
+        characters_key:
+            Key name used for character definitions when a *raw* map is supplied.
+        symbols_key:
+            Key name used for symbol definitions when a *raw* map is supplied.
+        case_sensitive:
+            When False (default), keys are normalized to uppercase.
+        fallback_char:
+            Glyph to use when a key is missing. Defaults to '?'. If the glyph for '?' is
+            unavailable the implementation falls back to ' ' when present, otherwise a
+            :class:`ValueError` is raised requesting an explicit fallback.
+
+    Properties:
+        is_case_sensitive (bool): Current case-sensitivity flag.
+        fallback_char (str): Current fallback character.
+        characters (list[str]): Keys in the character sub-map (if available).
+        symbols (list[str]): Keys in the symbol sub-map (if available).
+        character_map (dict[str, Glyph]): Raw character map (best-effort).
+        symbol_map (dict[str, Glyph]): Raw symbol map (best-effort).
+
+    Methods:
+        lookup(key: str, kind: Optional[str] = None) -> Glyph
+            Look up a glyph, optionally forcing 'character' or 'symbol'.
+        reload(font_map: dict) -> None
+            Replace the underlying map and rebuild indexes.
+
+    Raises:
+        ValueError:
+            - If `fallback_char` is not a single character.
+    Example Usage:
+        fm = FontMap()                     # load built-ins
+        g_q = fm.get('?')                  # dict-like get
+        g_a = fm['A']                      # Mapping access (uses fallback if missing)
+        fm.is_case_sensitive = True        # switch mode and reindex
+        fm.fallback_char = ' '             # change fallback
+        g = fm.lookup('→', kind='symbol')  # force symbol map
+    """
+
+    _glyphs: Dict[str, Glyph]
+    _raw_map: Optional[Dict[str, Dict[str, Glyph]]]
+    _characters_key: str
+    _symbols_key: str
+    _case_sensitive: bool
+    _fallback_char: str
+
+    DEFAULT_FALLBACK_CHAR: str = '?'
+
+    def __init__(
+        self,
+        font_map: Optional[Dict[str, Any]] = None,
+        *,
+        characters_key: str = 'characters',
+        symbols_key: str = 'symbols',
+        case_sensitive: bool = False,
+        fallback_char: Optional[str] = None
+    ) -> None:
+        self._characters_key = characters_key
+        self._symbols_key = symbols_key
+        self._case_sensitive = case_sensitive
+        self._fallback_char = fallback_char or '?'
+        self._raw_map = None
+        self._glyphs = {}
+
+        # Load data
+        if font_map is None:
+            # Prefer helper: expected to return a combined {str: Glyph} mapping.
+            data = load_builtin_char_map()
+            self._ingest_unknown_map(data)
+        else:
+            self._ingest_unknown_map(font_map)
+
+        self._validate_fallback()
+
+    # ---------- ingestion / normalization ----------
+
+    def _looks_like_raw_map(self, data: Dict[str, Any]) -> bool:
+        return (
+                isinstance(data, dict)
+                and (has_key_ignore_case(data, self._characters_key) or has_key_ignore_case(data, self._symbols_key))
+                and isinstance(get_ignore_case(data, self._characters_key, {}), dict)
+                and isinstance(get_ignore_case(data, self._symbols_key, {}), dict)
+        )
+
+    def _ingest_unknown_map(self, data: Dict[str, Any]) -> None:
+        if self._looks_like_raw_map(data):
+            chars = dict(get_ignore_case(data, self._characters_key, {}) or {})
+            syms = dict(get_ignore_case(data, self._symbols_key, {}) or {})
+            self._raw_map = {'characters': chars, 'symbols': syms}
+            self._glyphs = {}
+            self._merge_into_glyphs(chars)
+            self._merge_into_glyphs(syms)
+        else:
+            self._raw_map = None
+            self._ingest_combined_map(data)  # treat as already-flat mapping
+
+    def _ingest_combined_map(self, combined: Dict[str, Glyph]) -> None:
+        self._raw_map = None
+        self._glyphs = {}
+        self._merge_into_glyphs(combined)
+
+    def _merge_into_glyphs(self, mapping: Dict[str, Glyph]) -> None:
+        if not mapping:
+            return
+        normalise: Callable[[str], str] = str if self._case_sensitive else lambda key: str(key).upper()
+        for k, v in mapping.items():
+            self._glyphs[normalise(k)] = v
+
+    def _normalize_key(self, key: str) -> str:
+        return key if self._case_sensitive else key.upper()
+
+    def _validate_fallback(self) -> None:
+        # Ensure fallback exists; prefer '?' then space, otherwise require an explicit fallback.
+        normalized = self._normalize_key(self._fallback_char)
+        if normalized in self._glyphs:
+            return
+
+        space_key = self._normalize_key(' ')
+        if space_key in self._glyphs:
+            self._fallback_char = ' '
+            return
+
+        if not self._glyphs:
+            raise ValueError('font_map must contain at least one glyph definition')
+
+        raise ValueError(
+            "Fallback character is missing from the font_map and no space fallback is available. "
+            "Provide a valid fallback_char or include an appropriate glyph."
+        )
+
+    # ---------- Mapping protocol ----------
+
+    def __getitem__(self, key: str) -> Glyph:
+        try:
+            return self._glyphs[self._normalize_key(key)]
+        except KeyError:
+            return self._glyphs[self._normalize_key(self._fallback_char)]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._glyphs)
+
+    def __len__(self) -> int:
+        return len(self._glyphs)
+
+    # dict-like conveniences
+    def get(self, key: str, default: Optional[Glyph] = None) -> Optional[Glyph]:  # type: ignore[override]
+        return self._glyphs.get(self._normalize_key(key), default)
+
+    def keys(self) -> Iterable[str]:  # type: ignore[override]
+        return self._glyphs.keys()
+
+    def values(self) -> Iterable[Glyph]:  # type: ignore[override]
+        return self._glyphs.values()
+
+    def items(self) -> Iterable[tuple[str, Glyph]]:  # type: ignore[override]
+        return self._glyphs.items()
+
+    def __contains__(self, key: object) -> bool:
+        return isinstance(key, str) and self._normalize_key(key) in self._glyphs
+
+    # ---------- Higher-level API ----------
+
+    def lookup(self, key: str, kind: Optional[str] = None) -> Glyph:
+        """
+        Lookup a character or symbol by key. If `kind` is provided, force that sub-map.
+
+        Parameters:
+            key:
+                The character/symbol to look up.
+            kind:
+                'character'/'char' or 'symbol' to force the specific sub-map. If not provided
+                or the raw segmentation is unavailable, falls back to the combined map.
+
+        Returns:
+            Glyph for `key`, or the configured fallback glyph if not present.
+        """
+        if kind is None or self._raw_map is None:
+            return self[key]
+
+        k = self._normalize_key(key)
+        if kind.lower().startswith('sym'):
+            return self._lookup_in(self._raw_map['symbols'], k)
+        if kind.lower().startswith('char'):
+            return self._lookup_in(self._raw_map['characters'], k)
+        return self[key]
+
+    def _lookup_in(self, mapping: Dict[str, Glyph], key: str) -> Glyph:
+        if not self._case_sensitive:
+            mapping = {str(k).upper(): v for k, v in mapping.items()}
+        return mapping.get(key, self._glyphs[self._normalize_key(self._fallback_char)])
+
+    def reload(self, font_map: Dict[str, Any]) -> None:
+        """
+        Reload the font map (raw or combined) and rebuild indexes.
+        """
+        self._ingest_unknown_map(font_map)
+        self._validate_fallback()
+
+    # ---------- Properties ----------
+
+    @property
+    def character_map(self) -> Dict[str, Glyph]:
+        if self._raw_map is None:
+            return dict(self._glyphs)  # best-effort: treat all as characters
+        return dict(self._raw_map['characters'])
+
+    @property
+    def symbol_map(self) -> Dict[str, Glyph]:
+        return {} if self._raw_map is None else dict(self._raw_map['symbols'])
+
+    @property
+    def characters(self) -> list[str]:
+        return list(self.character_map.keys())
+
+    @property
+    def symbols(self) -> list[str]:
+        return list(self.symbol_map.keys())
+
+    @property
+    def fallback_char(self) -> str:
+        return self._fallback_char
+
+    @fallback_char.setter
+    def fallback_char(self, new: str) -> None:
+        if not isinstance(new, str) or len(new) != 1:
+            raise ValueError('fallback_char must be a single character string')
+        self._fallback_char = new
+        self._validate_fallback()
+
+    @property
+    def is_case_sensitive(self) -> bool:
+        return self._case_sensitive
+
+    @validate_type(bool)
+    @is_case_sensitive.setter
+    def is_case_sensitive(self, new: bool) -> None:
+        if new is self._case_sensitive:
+            return
+        # Rebuild normalized key index under the new rule.
+        self._case_sensitive = new
+        existing = dict(self._glyphs)
+        self._glyphs.clear()
+        self._merge_into_glyphs(existing)
+        self._validate_fallback()
+
+    def __repr__(self) -> str:
+        return (
+            f'{self.__class__.__name__}('
+            f'case_sensitive={self._case_sensitive}, '
+            f'fallback_char={self._fallback_char!r}, '
+            f'count={len(self)}'
+            f')'
+        )