IS-Matrix-Forge 1.0.0.dev1__py3-none-any.whl

is_matrix_forge/assets/font_map.py

@@ -0,0 +1,119 @@
+import json
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+from inspyre_toolbox.syntactic_sweets.classes.decorators import validate_type
+
+
+class FontMap:
+    """
+    FontMap allows lookup of character and symbol patterns from a JSON-based font map.
+    """
+    DEFAULT_FALLBACK_CHAR = '?'
+
+    def __init__(
+        self,
+        font_map: Optional[Dict[str, Dict[str, List[int]]]] = None,
+        characters_key: str = 'characters',
+        symbols_key: str = 'symbols',
+        case_sensitive: bool = False,
+        fallback_char: Optional[str] = None
+    ):
+        """
+        Initialize a FontMap instance.
+
+        Parameters:
+            font_map: Raw font map dict loaded from JSON (or None to load from JSON file).
+            characters_key: Top-level key for character definitions.
+            symbols_key: Top-level key for symbol definitions.
+            case_sensitive: Toggle case-sensitive lookup.
+            fallback_char: Character to use when lookup fails.
+        """
+        # Lazy-load from JSON if not provided
+        if font_map is None:
+            map_path = Path(__file__).parent / 'font_map.json'
+            font_map = json.load(open(map_path))
+
+        self._map = font_map
+        self._characters_key = characters_key
+        self._symbols_key = symbols_key
+        self._case_sensitive = case_sensitive
+        self._fallback_char = fallback_char or self.DEFAULT_FALLBACK_CHAR
+
+    @property
+    def character_map(self) -> Dict[str, List[int]]:
+        return self._map[self._characters_key]
+
+    @property
+    def symbol_map(self) -> Dict[str, List[int]]:
+        return self._map[self._symbols_key]
+
+    @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):
+        if not isinstance(new, str) or len(new) != 1:
+            raise ValueError('fallback_char must be a single character string')
+        if new not in self.characters + self.symbols:
+            raise ValueError(f'{new!r} not found in font map')
+        self._fallback_char = new
+
+    @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):
+        self._case_sensitive = new
+
+    def __contains__(self, key: str) -> bool:
+        key_norm = self._normalize_key(key)
+        return key_norm in self.character_map or key_norm in self.symbol_map
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}(case_sensitive={self._case_sensitive}, "
+            f"fallback_char={self._fallback_char!r})"
+        )
+
+    def lookup(self, key: str, kind: Optional[str] = None) -> List[int]:
+        """
+        Lookup a character or symbol. If kind is 'character' or 'symbol', force that map.
+        """
+        key_norm = self._normalize_key(key)
+        if kind == 'symbol':
+            return self._lookup_map(self.symbol_map, key_norm)
+        if kind in ('char', 'character'):
+            return self._lookup_map(self.character_map, key_norm)
+
+        # Try characters first, then symbols
+        try:
+            return self._lookup_map(self.character_map, key_norm)
+        except KeyError:
+            return self._lookup_map(self.symbol_map, key_norm)
+
+    def reload(self, font_map: Union[str, Path, Dict]):
+        """
+        Reloads font map from a file path or dict.
+        """
+        if isinstance(font_map, (str, Path)):
+            font_map = json.load(open(font_map))
+        self._map = font_map
+
+    def _normalize_key(self, key: str) -> str:
+        return key if self._case_sensitive else key.upper()
+
+    def _lookup_map(self, mapping: Dict[str, List[int]], key: str) -> List[int]:
+        if key not in mapping:
+            key = self._fallback_char
+        return mapping[key]

is_matrix_forge/common/decorators/__init__.py

@@ -0,0 +1,152 @@
+import functools
+from typing import Optional, Type, Callable, Any
+
+import functools
+from typing import Optional, Type, Callable, Any
+from inspyre_toolbox.syntactic_sweets.classes.decorators import validate_type
+from is_matrix_forge.led_matrix.errors.misc import ImplicitNameDerivationError
+
+
+def freeze_setter(
+    attr_name: Optional[str] = None,
+    exception: Type[Exception] = AttributeError,
+    allow_none_reassignment: bool = False,
+    treat_none_as_unset: bool = True,
+    allow_reassignment_to_same_value: bool = False,
+    fail_silently: bool = False
+):
+    """
+    Function decorator for a @<prop>.setter that raises if you try to set again.
+
+    This decorator prevents reassigning a property after it's been set once,
+    with configurable exceptions.
+
+    Parameters:
+        attr_name (str, optional):
+            The name of the underlying private attribute to check. If not provided,
+            it will be derived from the setter's function name by prepending a
+            single underscore (e.g., `value` becomes `_value`). If your setter
+            name starts with a single underscore (e.g., `_internal_val`), you *must*
+            provide this parameter explicitly.
+        exception (Exception class, optional):
+            The exception to raise on reassignment.
+            Defaults to raise an AttributeError.
+        allow_none_reassignment (bool, optional):
+            If True, allows setting the property to None even if it's already set.
+            Defaults to False.
+        treat_none_as_unset (bool, optional):
+            If True, None values are considered as unset, allowing the property
+            to be set if its current value is None.
+            Defaults to True.
+        allow_reassignment_to_same_value (bool, optional):
+            If True, allows reassigning the property with the same value.
+            It passes silently and does not call the setter again.
+            Defaults to False.
+        fail_silently (bool, optional):
+            If True, instead of raising an exception on a forbidden reassignment,
+            the setter simply returns silently.
+            Defaults to False.
+
+    Raises:
+        ImplicitNameDerivationError:
+            If the decorated setter's name starts with a single underscore
+            (but not a double underscore, which has its own meaning) and
+            `attr_name` is not provided. This is to prevent accidental
+            triggering of Python's name mangling.
+        exception: (Defaults to AttributeError)
+            Raised when a forbidden attempt to reassign the property occurs,
+            unless `fail_silently` is True.
+
+    Example:
+        ```python
+        class MyClass:
+            def __init__(self):
+                self._value = None # Underlying attribute
+
+            @property
+            def value(self):
+                return self._value
+
+            @value.setter
+            @freeze_setter() # Derives attr_name as '_value'
+            def value(self, new_value):
+                self._value = new_value
+
+        obj = MyClass()
+        obj.value = 42
+        # obj.value = 100  # Raises AttributeError
+
+        class InternalPropClass:
+            def __init__(self):
+                self.__internal_storage = None # Explicit private attribute
+
+            @property
+            def _internal_prop(self):
+                return self.__internal_storage
+
+            @_internal_prop.setter
+            @freeze_setter(attr_name='__internal_storage') # Must provide attr_name
+            def _internal_prop(self, new_value):
+                self.__internal_storage = new_value
+        ```
+
+    See Also:
+        - `ImplicitNameDerivationError`: Raised for configuration issues with underscore-prefixed setters.
+        - `AttributeError`: Default exception for reassigning a frozen attribute.
+    """
+    def decorator(setter: Callable) -> Callable:
+        setter_name = setter.__name__
+
+        # Check if the setter name starts with a single '_' and attr_name isn't provided.
+        # We allow double underscores ('__') as they have special meaning and are less likely
+        # to be used for regular property setters that would rely on implicit derivation.
+        if setter_name.startswith('_') and not setter_name.startswith('__') and attr_name is None:
+            raise ImplicitNameDerivationError()  # Raise error if no explicit attr_name is given for such setters.
+
+        private_attr_name = attr_name or f'_{setter_name}'
+
+        @functools.wraps(setter)
+        def wrapper(self, new_value: Any) -> Any:
+            current_value = getattr(self, private_attr_name, None)
+
+            # Determine if the attribute is considered 'set'
+            # An attribute is considered "set" if:
+            # 1. treat_none_as_unset is False (meaning None is a valid set value)
+            # OR
+            # 2. treat_none_as_unset is True AND current_value is not None
+            is_set = not treat_none_as_unset or current_value is not None
+
+            if is_set:
+                # Case 1: Reassigning to the same value is allowed and current value matches new value
+                if allow_reassignment_to_same_value and new_value == current_value:
+                    return  # Pass silently without calling setter or raising
+
+                # Case 2: Reassigning to None is allowed and new value is None
+                # This only applies if the property is already considered "set".
+                # If treat_none_as_unset is True, setting to None effectively "unsets" it.
+                if allow_none_reassignment and new_value is None:
+                    return setter(self, new_value)  # Allow and call setter
+
+                # Case 3: Forbidden reassignment
+                if fail_silently:
+                    return  # Fail silently
+
+                raise exception(
+                    f"Cannot reassign {self.__class__.__name__}.{setter_name} "
+                    f"(current value: {current_value!r}, private attribute: '{private_attr_name}')"
+                )
+
+            # If the attribute wasn't considered set, or if it's being set to None
+            # when treat_none_as_unset is True (which is like an initial set), call the setter.
+            return setter(self, new_value)
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = [
+    'ImplicitNameDerivationError',
+    'freeze_setter',
+    'validate_type',
+]

is_matrix_forge/common/dirs.py

@@ -0,0 +1,20 @@
+"""
+Directory configuration for the LED Matrix Battery application.
+
+This module provides platform-specific directory paths for storing application
+data, configuration files, and other resources using the platformdirs library.
+"""
+
+from platformdirs import PlatformDirs
+
+
+APP_DIRS    = PlatformDirs('LEDMatrixLib', appauthor='Inspyre Softworks')
+APP_DIR     = APP_DIRS.user_data_path
+PRESETS_DIR = APP_DIR.joinpath('presets')
+
+
+__all__ = [
+    'APP_DIRS',
+    'APP_DIR',
+    'PRESETS_DIR',
+]

is_matrix_forge/common/helpers/__init__.py

@@ -0,0 +1,132 @@
+import hashlib
+from pathlib import Path
+from typing import Optional
+import requests
+from inspyre_toolbox.path_man import provision_path
+
+
+def download_presets():
+    from is_matrix_forge.led_matrix.constants import PROJECT_URLS
+
+    url = PROJECT_URLS['github_api']
+
+
+
+def calculate_checksum(file_path):
+    """
+    Calculate the SHA-256 checksum of a file.
+
+    Parameters:
+        file_path (Union[str, Path]):
+            The path to the file for which to calculate the checksum.
+
+    Returns:
+        str:
+            The SHA-256 checksum of the file.
+    """
+    if not isinstance(file_path, Path):
+        file_path = provision_path(file_path)
+
+    sha256 = hashlib.sha256()
+
+    with open(file_path, 'rb') as f:
+        for chunk in iter(lambda: f.read(4096), b''):
+            sha256.update(chunk)
+
+    return sha256.hexdigest()
+
+
+def coerce_to_int(value) -> Optional[int]:
+    """
+    Attempt to coerce a value to an integer.
+
+    Parameters:
+        value (Any):
+            The value to coerce.
+
+    Returns:
+        Optional[int]:
+            The coerced integer value, or None if the coercion fails.
+    """
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def percentage_to_value(percent, max_value=255):
+    """
+    Convert a percentage value to an actual value between 0 and `max_value`.
+
+    Parameters:
+        percent (float):
+            The percentage value to convert.
+
+        max_value (int, optional):
+            The maximum value to which the percentage should be converted. Defaults to 255.
+
+    Returns:
+        int:
+            The converted value between 0 and `max_value`.
+    """
+    if not isinstance(percent, (int, float)):
+        raise TypeError(f'percent must be of type int or float, not {type(percent)}')
+
+    if percent < 0 or percent > 100:
+        raise ValueError(f'percent must be between 0 and 100, not {percent}')
+
+    return int(round(percent * max_value / 100))
+
+
+def verify_checksum(remote_checksum, local_file_path):
+    """
+    Verify the checksum of a local file against a remote checksum.
+
+    Parameters:
+        remote_checksum (str):
+            The remote checksum to verify against.
+
+        local_file_path (Union[str, Path]):
+            The path to the local file to verify.
+
+    Returns:
+        bool:
+            True if the checksums match, False otherwise.
+    """
+    if not isinstance(local_file_path, Path):
+        local_file_path = provision_path(local_file_path)
+
+    sha256 = hashlib.sha256()
+
+    with open(local_file_path, 'rb') as f:
+        for chunk in iter(lambda: f.read(4096), b''):
+            sha256.update(chunk)
+
+    local_checksum = sha256.hexdigest()
+
+    return local_checksum == remote_checksum
+
+
+def download_file(url, local_path, headers=None):
+    """
+    Download a file from a URL and save it to a local path.
+
+    Parameters:
+        url (str):
+            The URL of the file to download.
+
+        local_path (Union[str, Path]):
+            The local path to save the downloaded file.
+
+        headers (Optional[Dict]):
+            The headers to use for the request. Defaults to None.
+    """
+    if not isinstance(local_path, Path):
+        local_path = provision_path(local_path)
+
+    response = requests.get(url, headers=headers, stream=True)
+    response.raise_for_status()
+
+    with open(local_path, 'wb') as f:
+        for chunk in response.iter_content(chunk_size=8192):
+            f.write(chunk)

is_matrix_forge/common/helpers/github_api.py

@@ -0,0 +1,67 @@
+"""
+
+
+Author: 
+    Inspyre Softworks
+
+Project:
+    led-matrix-battery
+
+File: 
+    is_matrix_forge/common/helpers/github_api.py
+ 
+
+Description:
+    
+
+"""
+from typing import Optional
+from is_matrix_forge.led_matrix.constants import PROJECT_URLS
+
+GITHUB_URL_SUFFIX = '?ref=main'
+
+
+def assemble_github_url_suffix(branch: Optional[str] = None):
+    """
+    Assemble the URL suffix for the GitHub link.
+
+    Parameters:
+        branch (Optional[str]):
+            The name of the target GitHub repo branch.
+            Optional, defaults to "main".
+
+    Returns:
+        str:
+            The GitHub URL suffix. Specifically, a reference tag to a target branch.
+    """
+    return f'?ref={branch or "main"}'
+
+
+def assemble_github_content_path_url(
+        relative_path: Optional[str] = 'presets',  # e.g. 'dev_tools/presets.py'
+        branch:        Optional[str] = 'master',
+        base_url:      Optional[str] = PROJECT_URLS['github_api'],
+        suffix:        Optional[str] = None
+):
+    """
+    Assemble a GitHub content path URL.
+
+    Parameters:
+        relative_path (Optional[str]):
+            The relative path to the file in the GitHub repository.
+        branch (Optional[str]):
+            The branch name. Defaults to 'master'.
+        base_url (Optional[str]):
+            The base URL of the GitHub API. Defaults to PROJECT_URLS['github_api'].
+        suffix (Optional[str]):
+            The URL suffix. Defaults to GITHUB_URL_SUFFIX.
+
+    Returns:
+        str:
+            The assembled GitHub content path URL.
+    """
+    return f"{base_url}/{relative_path}{suffix or assemble_github_url_suffix(branch)}"
+
+
+REPO_PRESETS_URL = assemble_github_content_path_url()
+

is_matrix_forge/designer_gui/__init__.py

@@ -0,0 +1,8 @@
+"""
+Author: Taylor B. tayjaybabee@gmail.com
+Date: 2025-04-30 16:01:10
+LastEditors: Taylor B. tayjaybabee@gmail.com
+LastEditTime: 2025-04-30 16:01:49
+FilePath: is_matrix_forge/designer_gui/__init__.py
+Description: 这是默认设置,可以在设置》工具》File Description中进行配置
+"""