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

{is_matrix_forge-1.0.0.dev9 → 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.dev9
+Version: 1.0.0.dev27
 Summary: 
 License: MIT
 Keywords: led,matrix,framework,hardware
@@ -28,7 +28,7 @@ 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)
+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
@@ -136,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
@@ -188,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.dev9 → 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/__init__.py

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

{is_matrix_forge-1.0.0.dev9 → 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/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')'
+        )

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

@@ -0,0 +1,132 @@
+# =============================================================================
+# Author      : Taylor-Jayde Blackstone / Inspyre Softworks
+# Project     : IS-Matrix-Forge
+# File        : is_matrix_forge/assets/font_map/builders.py
+#
+# Description :
+#   Adapter/builder for turning flat 5x6 (length-30) 0/1 glyph lists into
+#   a raw map suitable for FontMap: {'characters': {...}, 'symbols': {...}}.
+#   Handles validation, reshaping to row-major 2D lists, and optional aliases.
+#
+# Dependencies:
+#   - is_matrix_forge/assets/font_map/models/glyph.py (Glyph type)
+#   - is_matrix_forge/assets/font_map/base.py (FontMap)
+# =============================================================================
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, Mapping, MutableMapping, Sequence, Tuple
+
+from .models.glyph import Glyph
+from .base import FontMap
+
+
+def _to_rows(flat: Sequence[int], width: int, height: int) -> Glyph:
+    """
+    Convert a flat 0/1 list into a row-major 2D structure that matches the Glyph type.
+
+    Parameters
+    ----------
+    flat :
+        Flat sequence of ints (0/1). Expected length == width * height.
+    width :
+        Glyph width (columns).
+    height :
+        Glyph height (rows).
+
+    Returns
+    -------
+    Glyph
+        Project Glyph value (list of lists of ints).
+    """
+    if len(flat) != width * height:
+        raise ValueError(f'Glyph length {len(flat)} != {width*height} (expected).')
+    if any(px not in (0, 1) for px in flat):
+        raise ValueError('Glyph data must be 0/1.')
+    return [list(flat[r * width:(r + 1) * width]) for r in range(height)]
+
+
+@dataclass(slots=True)
+class FontMapBuilder5x6:
+    """
+    Build a FontMap from flat 5x6 glyph dictionaries (characters + symbols).
+
+    Parameters
+    ----------
+    width :
+        Glyph width in pixels. Default 5.
+    height :
+        Glyph height in pixels. Default 6.
+    case_sensitive :
+        Whether keys should remain case-sensitive in the produced map.
+    fallback_char :
+        Fallback character key to ensure is present in the output (e.g., '?').
+
+    Notes
+    -----
+    - Input dicts should be {str: List[int]} with length-30 lists.
+    - Aliases are additional keys pointing at an existing glyph key.
+    """
+    width: int = 5
+    height: int = 6
+    case_sensitive: bool = False
+    fallback_char: str = '?'
+    _chars: MutableMapping[str, Glyph] = field(default_factory=dict, init=False)
+    _syms: MutableMapping[str, Glyph] = field(default_factory=dict, init=False)
+
+    # --- Registration --------------------------------------------------------
+
+    def add_char_map(self, mapping: Mapping[str, Sequence[int]]) -> 'FontMapBuilder5x6':
+        """Register many character glyphs from a flat 0/1 list mapping."""
+        for k, v in mapping.items():
+            key = k if self.case_sensitive else str(k).upper()
+            self._chars[key] = _to_rows(v, self.width, self.height)
+        return self
+
+    def add_symbol_map(self, mapping: Mapping[str, Sequence[int]]) -> 'FontMapBuilder5x6':
+        """Register many symbol glyphs from a flat 0/1 list mapping."""
+        for k, v in mapping.items():
+            key = k if self.case_sensitive else (k if len(k) != 1 else k.upper())
+            self._syms[key] = _to_rows(v, self.width, self.height)
+        return self
+
+    def add_aliases(self, aliases: Mapping[str, str]) -> 'FontMapBuilder5x6':
+        """
+        Add alias keys that point to existing glyphs.
+
+        Example:
+            builder.add_aliases({'°C': 'degC', '°F': 'degF'})
+        """
+        for alias, target in aliases.items():
+            # Try symbols first, then characters
+            if target in self._syms:
+                self._syms[alias] = self._syms[target]
+            elif target in self._chars:
+                self._syms[alias] = self._chars[target]
+            else:
+                tnorm = target if self.case_sensitive else target.upper()
+                if tnorm in self._chars:
+                    self._syms[alias] = self._chars[tnorm]
+                elif tnorm in self._syms:
+                    self._syms[alias] = self._syms[tnorm]
+                else:
+                    raise KeyError(f'Alias target {target!r} not found in current maps.')
+        return self
+
+    # --- Output --------------------------------------------------------------
+
+    def build_raw(self) -> Dict[str, Dict[str, Glyph]]:
+        """Produce a raw map suitable for FontMap(font_map=RAW)."""
+        return {'characters': dict(self._chars), 'symbols': dict(self._syms)}
+
+    def build_font_map(self) -> FontMap:
+        """Construct and return a FontMap from the accumulated maps."""
+        raw = self.build_raw()
+        return FontMap(
+            font_map=raw,
+            characters_key='characters',
+            symbols_key='symbols',
+            case_sensitive=self.case_sensitive,
+            fallback_char=self.fallback_char,
+        )

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

@@ -0,0 +1,35 @@
+from typing import Dict, Any
+
+from importlib.resources import files
+import json
+
+from .models.glyph import Glyph
+
+
+def load_builtin_char_map() -> Dict[str, Glyph]:
+    resource = files('is_matrix_forge.assets').joinpath('char_map.json')
+    if not resource.is_file():
+        raise FileNotFoundError('char_map.json missing from is_matrix_forge.assets package data')
+    data = json.loads(resource.read_text())
+
+    return dict(data)
+
+
+def has_key_ignore_case(
+        d: Dict[str, Any],
+        key: str
+) -> bool:
+    kf = key.casefold()
+
+    return any(k.casefold() == kf for k in d)
+
+
+def get_ignore_case(
+        d: Dict[str, Any],
+        key: str,
+        default=None
+):
+    kf = key.casefold()
+
+    return next((v for k, v in d.items() if k.casefold() == kf), default)
+

is_matrix_forge-1.0.0.dev27/is_matrix_forge/assets/font_map/models/__init__.py

@@ -0,0 +1,17 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    IS-Matrix-Forge
+
+File: 
+    is_matrix_forge/assets/font_map/models/__init__.py
+ 
+
+Description:
+    
+
+"""

is_matrix_forge-1.0.0.dev27/is_matrix_forge/assets/font_map/models/glyph.py

@@ -0,0 +1,4 @@
+from typing import List
+
+
+Glyph = List[List[int]]

{is_matrix_forge-1.0.0.dev9 → is_matrix_forge-1.0.0.dev27}/is_matrix_forge/common/helpers/__init__.py

@@ -1,8 +1,15 @@
 import hashlib
 from pathlib import Path
 from typing import Optional
-import requests
-from inspyre_toolbox.path_man import provision_path
+try:
+    import requests
+except ModuleNotFoundError:  # pragma: no cover - optional dependency
+    requests = None
+try:
+    from inspyre_toolbox.path_man import provision_path
+except ModuleNotFoundError:  # pragma: no cover - fallback
+    def provision_path(path):
+        return Path(path)
 from is_matrix_forge.log_engine import ROOT_LOGGER
 
 

is_matrix_forge-1.0.0.dev27/is_matrix_forge/common/helpers/errors.py

@@ -0,0 +1,23 @@
+from is_matrix_forge.log_engine import ROOT_LOGGER
+
+
+MOD_LOGGER = ROOT_LOGGER.get_child('common.helpers.errors')
+
+
+
+def catch_and_notify(
+    exception: Exception,
+    operation: str,
+    op_args: tuple = (),
+    op_kwargs: dict = {},
+    logger = MOD_LOGGER,
+    log_level = 'error'
+) -> None:
+    """
+    Catch and notify an exception.
+    """
+    logger.log(
+        log_level,
+        f'Operation "{operation}" failed with exception: {exception}'
+    )
+)

is_matrix_forge-1.0.0.dev27/is_matrix_forge/common/logging/__init__.py

@@ -0,0 +1,17 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    IS-Matrix-Forge
+
+File: 
+    is_matrix_forge/common/logging/__init__.py
+ 
+
+Description:
+    
+
+"""