basebender 0.2.1__py3-none-any.whl

basebender/rebaser/config_loader.py

@@ -0,0 +1,269 @@
+"""
+This module handles
+loading and saving configuration for digit sets and UI state.
+
+It defines paths for package, system, and user configuration files,
+and provides functions to load digit sets from TOML files
+and manage the application's UI state.
+"""
+
+import importlib.resources
+import logging
+import os
+from pathlib import Path
+from typing import Any, cast
+
+import toml
+
+from .models import DigitSet
+
+logger = logging.getLogger(__name__)
+
+
+def _get_config_paths() -> tuple[Path, Path | None, Path | None, Path | None]:
+    """
+    Determines the paths for package, system, and user configuration files.
+
+    This function calculates the expected paths for `default_digit_sets.toml`
+    (within the package), `digit_sets.toml` (system-wide and user-specific),
+    and `ui_state.toml` (user-specific) based on the operating system.
+
+    Returns:
+        A tuple containing:
+        - package_config_path (Path): Path to the default digit sets TOML file
+          within the installed package.
+        - system_config_path (Optional[Path]): Path to the system-wide digit
+          sets TOML file, or None if not applicable for the OS.
+        - user_config_path (Optional[Path]): Path to the user-specific digit
+          sets TOML file, or None if not applicable for the OS.
+        - ui_state_path (Optional[Path]): Path to the user-specific UI state
+          TOML file, or None if not applicable for the OS.
+    """
+    package_config_path = Path(
+        cast(
+            str,
+            importlib.resources.files("basebender.rebaser.resources.data")
+            / "default_digit_sets.toml",
+        )
+    )
+
+    # System config path (platform-dependent)
+    if os.name == "posix":  # Linux, macOS
+        system_config_path = Path("/etc") / "basebender" / "digit_sets.toml"
+    elif os.name == "nt":  # Windows
+        system_config_path = (
+            Path(os.environ.get("PROGRAMDATA", "C:\\ProgramData"))
+            / "basebender"
+            / "digit_sets.toml"
+        )
+    else:
+        system_config_path = None  # Fallback for unknown OS
+
+    # User config path (platform-dependent)
+    user_config_dir = None
+    if os.name == "posix":
+        user_config_dir = Path.home() / ".config" / "basebender"
+    elif os.name == "nt":
+        user_config_dir = Path(os.environ.get("APPDATA", Path.home())) / "basebender"
+
+    user_config_path = user_config_dir / "digit_sets.toml" if user_config_dir else None
+    ui_state_path = user_config_dir / "ui_state.toml" if user_config_dir else None
+
+    return (
+        package_config_path,
+        system_config_path,
+        user_config_path,
+        ui_state_path,
+    )
+
+
+def load_digit_sets_from_toml(filepath: Path, source_type: str) -> list[DigitSet]:
+    """
+    Loads digit sets from a TOML file, associating them with a given source type.
+
+    Args:
+        filepath: The path to the TOML file containing digit set definitions.
+        source_type: A string indicating the source of these digit sets (e.g.,
+                     "package", "system", "user").
+
+    Returns:
+        A list of `DigitSet` objects loaded from the file. Returns an empty list
+        if the file is not found, is malformed, or contains invalid entries.
+    """
+    loaded_digit_sets: list[DigitSet] = []
+    try:
+        with open(filepath, encoding="utf-8") as file_ptr:
+            config = toml.load(file_ptr)
+
+        digit_sets_data = config.get("digit_sets", [])
+        if not isinstance(digit_sets_data, list):
+            logger.warning("'%s' in %s is not a list. Skipping.", "digit_sets", filepath)
+            return loaded_digit_sets
+
+        for digit_set_entry in digit_sets_data:
+            if not isinstance(digit_set_entry, dict):
+                logger.warning(
+                    "Found non-dictionary item in 'digit_sets' in %s. Skipping: %s",
+                    filepath,
+                    digit_set_entry,
+                )
+                continue
+
+            digit_set_name = digit_set_entry.get("name")
+            digits = digit_set_entry.get("digits")
+
+            if not isinstance(digit_set_name, str) or not digit_set_name:
+                logger.warning(
+                    "No 'name' found for a digit set entry in %s. Skipping: %s",
+                    filepath,
+                    digit_set_entry,
+                )
+                continue
+            if not isinstance(digits, str) or not digits:
+                logger.warning(
+                    "Digit set entry '%s' in %s missing or invalid 'digits'. Skipping.",
+                    digit_set_name,
+                    filepath,
+                )
+                continue
+
+            loaded_digit_sets.append(
+                DigitSet(name=digit_set_name, digits=digits, source=source_type)
+            )
+    except FileNotFoundError:
+        pass  # No digit sets from this file, which is fine
+    except toml.TomlDecodeError as exc:
+        logger.warning("Error decoding TOML file %s: %s", filepath, exc)
+    except OSError as exc:  # Use OSError for modern Python
+        logger.warning("An unexpected error occurred while loading %s: %s", filepath, exc)
+    return loaded_digit_sets
+
+
+def get_all_digit_sets() -> dict[str, DigitSet]:
+    """
+    Loads and merges digit sets from package, system, and user configurations.
+
+    The loading order defines precedence: user configuration overrides system,
+    and system overrides package defaults. Each digit set is assigned a unique
+    ID based on its source and name (e.g., "package:ASCII").
+
+    Returns:
+        A dictionary where keys are unique IDs (e.g., "package:ASCII") and
+        values are `DigitSet` objects.
+    """
+    package_path, system_path, user_path, _ = _get_config_paths()
+
+    all_digit_sets_list: list[DigitSet] = []
+
+    # Load package digit sets
+    all_digit_sets_list.extend(load_digit_sets_from_toml(package_path, "package"))
+
+    # Load system digit sets
+    if system_path and system_path.exists():
+        all_digit_sets_list.extend(load_digit_sets_from_toml(system_path, "system"))
+
+    # Load user digit sets (highest precedence)
+    if user_path and user_path.exists():
+        all_digit_sets_list.extend(load_digit_sets_from_toml(user_path, "user"))
+
+    # Convert list to a dictionary with unique IDs, handling precedence.
+    # Process in reverse (user -> system -> package) so highest-precedence entries
+    # are written first and lower-precedence entries overwrite them last.
+    final_digit_sets: dict[str, DigitSet] = {}
+    for current_digit_set_obj in reversed(all_digit_sets_list):
+        unique_id = f"{current_digit_set_obj.source}:{current_digit_set_obj.name}"
+        final_digit_sets[unique_id] = current_digit_set_obj
+
+    return final_digit_sets
+
+
+def get_ui_state_path() -> Path | None:
+    """
+    Returns the path to the user's UI state configuration file.
+
+    This file is typically located in a user-specific configuration directory.
+
+    Returns:
+        A `Path` object pointing to the UI state file, or `None` if the
+        user configuration directory cannot be determined for the current OS.
+    """
+    _, _, _, ui_state_path = _get_config_paths()
+    return ui_state_path
+
+
+def load_ui_state() -> dict[str, Any]:
+    """
+    Loads the UI state from the user's configuration file.
+
+    Returns:
+        A dictionary containing the loaded UI state. Returns an empty dictionary
+        if the file does not exist, is malformed, or an error occurs during loading.
+    """
+    ui_state_path = get_ui_state_path()
+    if ui_state_path and ui_state_path.exists():
+        try:
+            with open(ui_state_path, encoding="utf-8") as file_ptr:
+                return cast(dict[str, Any], toml.load(file_ptr))
+        except toml.TomlDecodeError as exc:
+            logger.warning("Error decoding UI state TOML file %s: %s", ui_state_path, exc)
+        except OSError as exc:  # Use OSError for modern Python
+            logger.warning(
+                "An unexpected error occurred while loading UI state from %s: %s",
+                ui_state_path,
+                exc,
+            )
+    return {}  # Return empty dict if file not found or error
+
+
+def save_ui_state(state_data: dict[str, Any]) -> None:
+    """
+    Saves the provided UI state data to the user's configuration file.
+
+    The function ensures that the parent directory for the UI state file exists.
+    Any errors during saving are logged.
+
+    Args:
+        state_data: A dictionary containing the UI state to be saved.
+    """
+    ui_state_path = get_ui_state_path()
+    if ui_state_path:
+        try:
+            ui_state_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(ui_state_path, "w", encoding="utf-8") as file_ptr:
+                toml.dump(state_data, file_ptr)
+        except OSError as exc:  # Use OSError for modern Python
+            logger.error("Could not save UI state to %s: %s", ui_state_path, exc)
+
+
+if __name__ == "__main__":
+    # Example usage for testing
+    print("--- Testing Digit Set Loading ---")
+    digit_sets = get_all_digit_sets()
+    print("Loaded Digit Sets:")
+    for name_key, digit_set_obj in digit_sets.items():
+        print(
+            f"  {name_key}: {digit_set_obj.digits} "
+            f"(Name: {digit_set_obj.name}, Source: {digit_set_obj.source})"
+        )
+
+    print("\n--- Testing UI State Saving/Loading ---")
+    test_state = {
+        "last_input": "Hello World",
+        "last_source_digit_set": "package:ASCII",
+        "last_target_digit_set": "package:Binary",
+        "realtime_enabled": True,
+    }
+    print(f"Saving test UI state: {test_state}")
+    save_ui_state(test_state)
+
+    loaded_state = load_ui_state()
+    print(f"Loaded UI state: {loaded_state}")
+    assert loaded_state == test_state, "Loaded state does not match saved state!"
+
+    # Clean up test state file
+    ui_path = get_ui_state_path()  # pylint: disable=invalid-name
+    if ui_path and ui_path.exists():
+        os.remove(ui_path)
+        print(f"Cleaned up {ui_path}")
+    else:
+        print("UI state file not found for cleanup.")

basebender/rebaser/digit_set_rebaser.py

@@ -0,0 +1,303 @@
+"""
+This module provides the core logic for rebasing strings between different
+digit sets.
+
+It includes the `DigitSetRebaser` class, which handles the conversion of
+strings from an input digit set to an output digit set, supporting dynamic
+derivation of the input digit set and various rebase operations.
+"""
+
+from .models import DigitSet
+
+
+class DigitSetRebaser:
+    """
+    A class to rebase strings between different digit sets (positional number
+    systems).
+
+    It supports explicit input and output digit sets, or dynamic derivation of
+    the input digit set based on the input string.
+    """
+
+    def __init__(
+        self,
+        out_digit_set: DigitSet | None = None,
+        in_digit_set: DigitSet | None = None,
+    ) -> None:
+        self._initial_input_digit_set: DigitSet | None = in_digit_set
+        self._initial_output_digit_set: DigitSet | None = out_digit_set
+        self._in_digit_set_map: dict[str, int] = {}
+        self._in_digit_set_list: list[str] = []
+        self._out_digit_set_map: dict[str, int] = {}
+        self._out_digit_set_list: list[str] = []
+
+        # Output digit set is always explicitly set or None;
+        # not dynamically determined in __init__
+        if out_digit_set:
+            out_digits = DigitSet.deduplicate_digits(out_digit_set.digits)
+            self._out_digit_set_map = {char: i for i, char in enumerate(out_digits)}
+            self._out_digit_set_list = list(out_digits)
+
+        # Input digit set is dynamically determined in rebase
+        # if _initial_input_digit_set is None
+        if in_digit_set:
+            in_digits = DigitSet.deduplicate_digits(in_digit_set.digits)
+            self._in_digit_set_map = {char: i for i, char in enumerate(in_digits)}
+            self._in_digit_set_list = list(in_digits)
+
+    @property
+    def initial_input_digit_set(
+        self,
+    ) -> DigitSet | None:
+        """
+        The initial input digit set provided during initialization.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(in_digit_set=DigitSet("0123456789"))
+            >>> rebaser.initial_input_digit_set.digits
+            '0123456789'
+        """
+        return self._initial_input_digit_set
+
+    @property
+    def initial_output_digit_set(
+        self,
+    ) -> DigitSet | None:
+        """
+        The initial output digit set provided during initialization.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(out_digit_set=DigitSet("abc"))
+            >>> rebaser.initial_output_digit_set.digits
+            'abc'
+        """
+        return self._initial_output_digit_set
+
+    @property
+    def input_digit_set_map(
+        self,
+    ) -> dict[str, int]:
+        """
+        A dictionary mapping characters to their integer positions for the input digit set.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(in_digit_set=DigitSet("012"))
+            >>> rebaser.input_digit_set_map
+            {'0': 0, '1': 1, '2': 2}
+        """
+        return self._in_digit_set_map
+
+    @property
+    def input_digit_set_list(
+        self,
+    ) -> list[str]:
+        """
+        An ordered list of characters representing the input digit set.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(in_digit_set=DigitSet("abc"))
+            >>> rebaser.input_digit_set_list
+            ['a', 'b', 'c']
+        """
+        return self._in_digit_set_list
+
+    @property
+    def output_digit_set_map(
+        self,
+    ) -> dict[str, int]:
+        """
+        A dictionary mapping characters to their integer positions for the output digit set.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(out_digit_set=DigitSet("xyz"))
+            >>> rebaser.output_digit_set_map
+            {'x': 0, 'y': 1, 'z': 2}
+        """
+        return self._out_digit_set_map
+
+    @property
+    def output_digit_set_list(
+        self,
+    ) -> list[str]:
+        """
+        An ordered list of characters representing the output digit set.
+
+        Examples:
+            >>> rebaser = DigitSetRebaser(out_digit_set=DigitSet("789"))
+            >>> rebaser.output_digit_set_list
+            ['7', '8', '9']
+        """
+        return self._out_digit_set_list
+
+    @staticmethod
+    def char_to_position(char: str, digit_set_map: dict[str, int]) -> int:
+        """
+        Converts a character to its numerical position within a given digit set map.
+
+        Args:
+            char: The character to convert.
+            digit_set_map: A dictionary mapping characters to their integer positions.
+
+        Returns:
+            The integer position of the character.
+
+        Raises:
+            ValueError: If the character is not found in the digit set.
+        """
+        if char not in digit_set_map:
+            raise ValueError(f"Character '{char}' not found in the digit set.")
+        return digit_set_map[char]
+
+    @staticmethod
+    def position_to_char(position: int, digit_set_list: list[str]) -> str:
+        """
+        Converts a numerical position to its corresponding character in a digit set list.
+
+        Args:
+            position: The integer position to convert.
+            digit_set_list: An ordered list of characters representing the digit set.
+
+        Returns:
+            The character at the specified position.
+
+        Raises:
+            IndexError: If the position is out of bounds for the digit set.
+        """
+        if not 0 <= position < len(digit_set_list):
+            raise IndexError(f"Position {position} is out of bounds for the digit set.")
+        return digit_set_list[position]
+
+    @staticmethod
+    def string_to_int_from_base(input_str: str, digit_set_map: dict[str, int], base: int) -> int:
+        """
+        Converts a string representation of a number from a given base to an integer.
+
+        Characters not present in the `digit_set_map` are ignored.
+
+        Args:
+            input_str: The input string to convert.
+            digit_set_map: A dictionary mapping characters to their integer positions
+                           in the source digit set.
+            base: The base of the input string's number system (length of the source digit set).
+
+        Returns:
+            The integer representation of the input string.
+        """
+        filtered_input_str = [char for char in input_str if char in digit_set_map]
+
+        if not filtered_input_str:
+            return 0
+
+        integer_value = 0
+        power = 0
+        for char in reversed(filtered_input_str):
+            position = digit_set_map[char]
+            integer_value += position * (base**power)
+            power += 1
+        return integer_value
+
+    @staticmethod
+    def int_to_string_in_base(integer_value: int, digit_set_list: list[str], base: int) -> str:
+        """
+        Converts an integer to its string representation in a given base.
+
+        Args:
+            integer_value: The integer to convert.
+            digit_set_list: An ordered list of characters representing the target digit set.
+            base: The base of the target number system (length of the target digit set).
+
+        Returns:
+            The string representation of the integer in the target base.
+
+        Raises:
+            ValueError: If the base is not greater than 0.
+        """
+        if base <= 0:
+            raise ValueError("Base must be greater than 0 for integer to string rebase.")
+
+        if base == 1:
+            return ""
+
+        if integer_value == 0:
+            return digit_set_list[0]
+
+        result_chars: list[str] = []
+        while integer_value > 0:
+            remainder = integer_value % base
+            result_chars.append(digit_set_list[remainder])
+            integer_value //= base
+
+        return "".join(reversed(result_chars))
+
+    def rebase(self, input_string: str) -> str:
+        """
+        Rebases the input string from its determined input digit set to the
+        specified output digit set.
+
+        This method handles various scenarios:
+        - If `input_string` is empty, returns the first character of the output
+          digit set if available, otherwise an empty string.
+        - If neither input nor output digit sets are explicitly provided,
+          returns the input string as-is.
+        - If only the output digit set is provided, the input digit set is
+          dynamically derived from the `input_string`.
+        - If only the input digit set is provided, the input string is filtered
+          to include only characters present in the input digit set.
+        - If both are provided or derived, performs the full rebase operation.
+
+        Args:
+            input_string: The string to be rebased.
+
+        Returns:
+            The rebased string.
+        """
+        if not input_string:
+            return self._out_digit_set_list[0] if self._out_digit_set_list else ""
+
+        effective_input_digit_set_map: dict[str, int]
+        effective_input_digit_set_list: list[str]
+
+        if self._initial_input_digit_set:
+            effective_input_digit_set_map = self._in_digit_set_map
+            effective_input_digit_set_list = self._in_digit_set_list
+        else:
+            # Dynamically derive input digit set from input_string
+            derived_digits = DigitSet.deduplicate_digits(input_string)
+            effective_input_digit_set_map = {char: i for i, char in enumerate(derived_digits)}
+            effective_input_digit_set_list = list(derived_digits)
+
+        # Scenario 1: No explicit output digit set, and no initial input digit set
+        # (meaning input digit set was dynamically derived).
+        # In this case, just return the input string as is.
+        if self._initial_output_digit_set is None and self._initial_input_digit_set is None:
+            return input_string
+
+        # Scenario 2: No explicit output digit set, but an initial input digit set
+        # was provided. Filter the input string based on the provided input digit set.
+        if self._initial_output_digit_set is None and self._initial_input_digit_set is not None:
+            filtered_string = "".join(
+                char for char in input_string if char in effective_input_digit_set_map
+            )
+            return filtered_string
+
+        # If the effective input digit set is empty or has only one character,
+        # and we are supposed to rebase, return the first char of output or empty.
+        if not effective_input_digit_set_list or len(effective_input_digit_set_list) <= 1:
+            return self._out_digit_set_list[0] if self._out_digit_set_list else ""
+
+        # If the output digit set is empty, return an empty string
+        if not self._out_digit_set_list:
+            return ""
+
+        # Perform the full rebase
+        integer_value = self.string_to_int_from_base(
+            input_string,
+            effective_input_digit_set_map,
+            len(effective_input_digit_set_list),
+        )
+        final_rebased_string = self.int_to_string_in_base(
+            integer_value,
+            self._out_digit_set_list,
+            len(self._out_digit_set_list),
+        )
+        return final_rebased_string

basebender/rebaser/digit_sets.py

@@ -0,0 +1,84 @@
+"""
+This module manages predefined digit sets and provides utility functions for
+suggesting digit sets based on input strings.
+
+It includes caching mechanisms for efficient retrieval of digit set data.
+"""
+
+import functools
+
+from .config_loader import get_all_digit_sets
+from .models import DigitSet
+
+
+@functools.cache
+def get_predefined_digit_sets() -> dict[str, DigitSet]:
+    """
+    Returns a dictionary of all loaded predefined digit sets.
+
+    This function loads digit sets from various configuration sources (package,
+    system, user) and caches the result for efficient retrieval on subsequent calls.
+    The loading order defines precedence: user configuration overrides system,
+    and system overrides package defaults.
+
+    Returns:
+        A dictionary where keys are unique IDs (e.g., "package:ASCII") and
+        values are `DigitSet` objects.
+    """
+    return get_all_digit_sets()
+
+
+def suggest_digit_sets(input_string: str) -> list[str]:
+    """
+    Suggests predefined digit sets that the `input_string` might belong to.
+
+    This function iterates through all known predefined digit sets and identifies
+    those that contain all characters present in the `input_string`.
+
+    Args:
+        input_string: The string for which to suggest digit sets.
+
+    Returns:
+        A list of digit set IDs (strings) that are relevant to the input string.
+        The list is currently not sophisticatedly ranked beyond basic matching.
+    """
+    if not input_string:
+        return []
+
+    predefined_digit_sets = get_predefined_digit_sets()
+    suggestions: list[str] = []
+
+    for digit_set_id, digit_set_info in predefined_digit_sets.items():
+        if all(char in digit_set_info.digits for char in input_string):
+            suggestions.append(digit_set_id)
+
+    # Basic ordering: exact matches first (if any), then others.
+    # For now, just return the list as is,
+    # more sophisticated ranking can be added later.
+    return suggestions
+
+
+def main() -> None:
+    """
+    Main function for example usage and testing of digit set functionalities.
+    """
+    print("All Predefined Digit Sets:")
+    for example_ds_id, example_ds_info in get_predefined_digit_sets().items():
+        print(
+            f"  {example_ds_id} (Name: {example_ds_info.name}, "
+            f"Source: {example_ds_info.source}): {example_ds_info.digits}"
+        )
+
+    test_string_binary = "010110"  # pylint: disable=invalid-name
+    test_string_decimal = "12345"  # pylint: disable=invalid-name
+    test_string_hex = "DEADBEEF"  # pylint: disable=invalid-name
+    test_string_mixed = "Hello World 123"  # pylint: disable=invalid-name
+
+    print(f"\nSuggestions for '{test_string_binary}': {suggest_digit_sets(test_string_binary)}")
+    print(f"Suggestions for '{test_string_decimal}': {suggest_digit_sets(test_string_decimal)}")
+    print(f"Suggestions for '{test_string_hex}': {suggest_digit_sets(test_string_hex)}")
+    print(f"Suggestions for '{test_string_mixed}': {suggest_digit_sets(test_string_mixed)}")
+
+
+if __name__ == "__main__":
+    main()

basebender/rebaser/generated/STRUCTURE.md

@@ -0,0 +1,10 @@
+# `src/rebaser/generated` Directory Structure
+
+This directory contains generated source files, created by `bin/update`.
+
+## Folders:
+
+
+## Files:
+
+*   [`app_resources_rc.py`](src/rebaser/generated/app_resources_rc.py): Python module generated from `app_resources.qrc` for Qt resources.