basebender 0.2.1__py3-none-any.whl

basebender/STRUCTURE.md

@@ -0,0 +1,13 @@
+# `src/` Directory Structure
+
+This directory contains the core source code for the application.
+
+## Folders:
+
+*   [`api/`](src/api/STRUCTURE.md): Contains the FastAPI application for the project's API.
+*   [`gui/`](src/gui/STRUCTURE.md): Contains the graphical user interface components.
+*   [`rebaser/`](src/rebaser/STRUCTURE.md): Contains the core rebase logic and related modules.
+
+## Files:
+
+*   [`cli.py`](src/cli.py): Implements the command-line interface for the application.

basebender/__init__.py

@@ -0,0 +1,8 @@
+"""Basebender: A Python package. Refer to the documentation for more details."""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    VERSION = version("basebender")  # <--- Replace "basebender" with your actual package name
+except PackageNotFoundError, ImportError:
+    VERSION = "0.0.0+unknown"

basebender/api/STRUCTURE.md

@@ -0,0 +1,7 @@
+# `src/api/` Directory Structure
+
+This directory contains the FastAPI application for the project's API.
+
+## Files:
+
+*   [`main.py`](src/api/main.py): The main entry point for the FastAPI application.

basebender/api/main.py

@@ -0,0 +1,249 @@
+"""
+This module defines the FastAPI application for the BaseBender API.
+
+It provides endpoints for listing available digit sets and rebaseing text
+between different digit sets.
+"""
+
+import functools
+
+import uvicorn
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel
+
+from basebender.rebaser.digit_set_rebaser import DigitSetRebaser
+from basebender.rebaser.digit_sets import get_predefined_digit_sets
+from basebender.rebaser.models import DigitSet
+
+APP = FastAPI(
+    title="BaseBender API",
+    description=(
+        "API for rebaseing text between different digit sets and listing available digit sets."
+    ),
+    version="1.0.0",
+)
+
+
+@functools.cache
+def _load_digit_set_data() -> dict[str, DigitSet]:
+    """
+    Loads and caches predefined digit set data.
+
+    Returns:
+        A dictionary mapping digit set IDs to DigitSet objects.
+    """
+    return get_predefined_digit_sets()
+
+
+@APP.get("/", include_in_schema=False)
+async def redirect_to_docs() -> RedirectResponse:
+    """
+    Redirects the root URL ("/") to the API documentation page ("/docs").
+
+    Returns:
+        A RedirectResponse to the /docs endpoint.
+    """
+    return RedirectResponse(url="/docs")
+
+
+class DigitSetInfo(BaseModel):
+    """
+    Pydantic model representing information about a digit set.
+
+    Attributes:
+        id: The unique identifier of the digit set (e.g., "binary", "decimal").
+        name: A human-readable name for the digit set (e.g., "Binary", "Decimal").
+        digits: The string containing all unique digits of the set in order.
+        source: The origin of the digit set (e.g., "predefined", "cli_input", "api_input").
+    """
+
+    id: str
+    name: str
+    digits: str
+    source: str
+
+
+@APP.get(
+    "/digitsets",
+    response_model=list[DigitSetInfo],
+    summary="List all available digit sets",
+)
+async def list_digit_sets() -> list[DigitSetInfo]:
+    """
+    Retrieves a list of all available digit sets, including their unique IDs,
+    names, digits, and source.
+    """
+    digit_sets = _load_digit_set_data()
+    digit_set_list: list[DigitSetInfo] = []
+    for digit_set_id, digit_set_info in digit_sets.items():
+        digit_set_list.append(
+            DigitSetInfo(
+                id=digit_set_id,
+                name=digit_set_info.name,
+                digits=digit_set_info.digits,
+                source=digit_set_info.source,
+            )
+        )
+    return digit_set_list
+
+
+class RebaseRequest(BaseModel):
+    """
+    Pydantic model for a rebase operation request.
+
+    Attributes:
+        input_text: The string to be rebased. Defaults to an empty string.
+        source_digit_set: An optional string representing the source digit set
+            (e.g., "0123456789ABCDEF"). If provided, takes precedence over `source_digit_set_id`.
+        source_digit_set_id: An optional ID of a predefined source digit set.
+        target_digit_set: An optional string representing the target digit set.
+            If provided, takes precedence over `target_digit_set_id`.
+        target_digit_set_id: An optional ID of a predefined target digit set.
+    """
+
+    input_text: str | None = ""
+    source_digit_set: str | None = None
+    source_digit_set_id: str | None = None
+    target_digit_set: str | None = None
+    target_digit_set_id: str | None = None
+
+
+class ErrorResponse(BaseModel):
+    """
+    Pydantic model for standard API error responses.
+
+    Attributes:
+        message: A concise summary of the error.
+        detail: An optional, more detailed explanation of the error.
+    """
+
+    message: str
+    detail: str | None = None
+
+
+class RebaseResponse(BaseModel):
+    """
+    Pydantic model for the response of a rebase operation.
+
+    Attributes:
+        rebased_text: The string after the rebase operation.
+        source_digit_set_used: A string indicating the source digit set that was used
+            (e.g., "Binary", "Provided: '012'").
+        target_digit_set_used: A string indicating the target digit set that was used
+            (e.g., "Decimal", "Provided: 'abc'").
+        error: An optional `ErrorResponse` object if an error occurred during rebase.
+    """
+
+    rebased_text: str
+    source_digit_set_used: str
+    target_digit_set_used: str
+    error: ErrorResponse | None = None
+
+
+@APP.post(
+    "/rebase",
+    response_model=RebaseResponse,
+    summary="Rebase text between digit sets",
+)
+async def rebase_text(request: RebaseRequest) -> RebaseResponse:
+    """
+    Rebasees input text from a source digit set to a target digit set.
+
+    - If `input_text` is not provided, an empty string is used.
+    - If `source_digit_set_id` is not provided, the source digit set is
+      dynamically derived from `input_text`.
+    - If `target_digit_set_id` is not provided, the input string is returned
+      with digits not in the derived/provided source digit set removed. If the
+      target digit set has a length of 1, an empty string will be returned.
+    """
+    digit_sets_data = _load_digit_set_data()
+
+    input_text: str = request.input_text if request.input_text is not None else ""
+    source_digit_set_obj: DigitSet | None = None
+    target_digit_set_obj: DigitSet | None = None
+    source_digit_set_name: str = "Dynamically Derived"
+    target_digit_set_name: str = "Echo Input"
+
+    # Determine source digit set
+    if request.source_digit_set:  # Direct digit set string takes precedence
+        source_digit_set_obj = DigitSet(
+            name="Provided", digits=request.source_digit_set, source="api_input"
+        )
+        source_digit_set_name = f"Provided: '{request.source_digit_set}'"
+    elif request.source_digit_set_id:
+        source_digit_set_obj = digit_sets_data.get(request.source_digit_set_id)
+        if source_digit_set_obj is None:
+            raise HTTPException(
+                status_code=400,
+                detail=ErrorResponse(
+                    message="Invalid Source Digit Set ID",
+                    detail=(
+                        f"Source digit set with ID '{request.source_digit_set_id}' not found."
+                    ),
+                ).model_dump(),
+            ) from None
+        source_digit_set_name = source_digit_set_obj.name
+
+    # Determine target digit set
+    if request.target_digit_set:  # Direct digit set string takes precedence
+        target_digit_set_obj = DigitSet(
+            name="Provided", digits=request.target_digit_set, source="api_input"
+        )
+        target_digit_set_name = f"Provided: '{request.target_digit_set}'"
+    elif request.target_digit_set_id:
+        target_digit_set_obj = digit_sets_data.get(request.target_digit_set_id)
+        if target_digit_set_obj is None:
+            raise HTTPException(
+                status_code=400,
+                detail=ErrorResponse(
+                    message="Invalid Target Digit Set ID",
+                    detail=(
+                        f"Target digit set with ID '{request.target_digit_set_id}' not found."
+                    ),
+                ).model_dump(),
+            ) from None
+        target_digit_set_name = target_digit_set_obj.name
+
+    rebased_text: str = ""
+    error_response: ErrorResponse | None = None
+
+    try:
+        rebaser = DigitSetRebaser(
+            out_digit_set=target_digit_set_obj,
+            in_digit_set=source_digit_set_obj,
+        )
+        rebased_text = rebaser.rebase(input_text)
+    except ValueError as exc:
+        error_response = ErrorResponse(
+            message="Rebase Error",
+            detail=f"A value error occurred during rebase: {exc}",
+        )
+        raise HTTPException(status_code=400, detail=error_response.model_dump()) from exc
+    except IndexError as exc:
+        error_response = ErrorResponse(
+            message="Rebase Error",
+            detail=f"An index error occurred during rebase: {exc}",
+        )
+        raise HTTPException(status_code=400, detail=error_response.model_dump()) from exc
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # Catching broad exception as an isolation point for unexpected errors.
+        error_response = ErrorResponse(
+            message="Internal Server Error",
+            detail=f"An unexpected error occurred: {exc}",
+        )
+        raise HTTPException(status_code=500, detail=error_response.model_dump()) from exc
+
+    return RebaseResponse(
+        rebased_text=rebased_text,
+        source_digit_set_used=source_digit_set_name,
+        target_digit_set_used=target_digit_set_name,
+        error=error_response,
+    )
+
+
+def start_api() -> None:
+    """
+    Starts the FastAPI server using uvicorn.
+    """
+    uvicorn.run("basebender.api.main:APP", host="0.0.0.0", port=8000, reload=True)

basebender/cli.py

@@ -0,0 +1,231 @@
+"""
+This module provides a command-line interface (CLI) for the BaseBender tool.
+
+It allows users to rebase strings between different digit sets, list available
+digit sets, suggest digit sets for a given string, and launch a graphical user
+interface or an API server.
+"""
+
+import argparse
+import logging
+import sys
+
+import uvicorn
+
+from basebender.rebaser.digit_set_rebaser import DigitSetRebaser
+from basebender.rebaser.digit_sets import (
+    get_predefined_digit_sets,
+    suggest_digit_sets,
+)
+from basebender.rebaser.models import DigitSet
+
+
+def list_digit_sets_cli() -> int:
+    """
+    Lists all available pre-defined digit sets to the console.
+
+    Returns:
+        An exit code (0 for success).
+    """
+    print("Pre-defined Digit Sets:")
+    digit_sets = get_predefined_digit_sets()
+    for digit_set_id, digit_set_info in digit_sets.items():
+        print(
+            f"  {digit_set_id} (Name: {digit_set_info.name}, "
+            f"Source: {digit_set_info.source}): {digit_set_info.digits}"
+        )
+    return 0
+
+
+def suggest_digit_sets_cli(input_string: str) -> int:
+    """
+    Suggests pre-defined digit sets based on characters in the input string.
+
+    Args:
+        input_string: The string for which to suggest digit sets.
+
+    Returns:
+        An exit code (0 for success).
+    """
+    suggestions = suggest_digit_sets(input_string)
+    if suggestions:
+        print(f"Suggested Digit Sets for '{input_string}':")
+        for suggestion in suggestions:
+            print(f"  - {suggestion}")
+    else:
+        print(f"No pre-defined digit sets suggested for '{input_string}'.")
+    return 0
+
+
+def perform_rebase_cli(
+    input_string: str | None,
+    output_digit_set_str: str | None,
+    input_digit_set_str: str | None,
+) -> int:
+    """
+    Performs the digit set rebase operation and prints the result to the console.
+
+    This function handles the dynamic derivation of input and output digit sets
+    from predefined sets or user-provided strings. It also includes error
+    reporting for invalid operations.
+
+    Args:
+        input_string: The string to be rebased.
+        output_digit_set_str: The identifier or string representation of the
+            target digit set.
+        input_digit_set_str: The identifier or string representation of the
+            source digit set.
+
+    Returns:
+        An exit code (0 for success, 1 for error).
+    """
+    if not input_string:
+        print("Rebased string: ")
+        return 0
+
+    digit_sets_data = get_predefined_digit_sets()
+    input_digit_set_obj: DigitSet | None = None
+    output_digit_set_obj: DigitSet | None = None
+
+    # Determine input digit set
+    if input_digit_set_str:
+        if input_digit_set_str in digit_sets_data:
+            input_digit_set_obj = digit_sets_data[input_digit_set_str]
+        else:
+            input_digit_set_obj = DigitSet(
+                name="Provided", digits=input_digit_set_str, source="cli_input"
+            )
+
+    # Determine output digit set
+    if output_digit_set_str:
+        if output_digit_set_str in digit_sets_data:
+            output_digit_set_obj = digit_sets_data[output_digit_set_str]
+        else:
+            output_digit_set_obj = DigitSet(
+                name="Provided", digits=output_digit_set_str, source="cli_input"
+            )
+
+    try:
+        rebaser = DigitSetRebaser(
+            out_digit_set=output_digit_set_obj, in_digit_set=input_digit_set_obj
+        )
+        rebased_string = rebaser.rebase(input_string)
+        print(f"Rebased string: {rebased_string}")
+        return 0
+    except ValueError as exc:
+        logging.error("Error: Invalid digit set or rebase operation. %s", exc)
+        return 1
+    except IndexError as exc:
+        logging.error(
+            "Error: Digit set index out of bounds. This usually indicates an "
+            "internal issue with digit set mapping. %s",
+            exc,
+        )
+        return 1
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # Catching broad exception as an isolation point for unexpected errors.
+        logging.error("An unexpected error occurred during rebase: %s", exc)
+        return 1
+
+
+def main() -> None:
+    """
+    Main entry point for the BaseBender command-line interface.
+
+    This function parses command-line arguments, handles various CLI operations
+    like listing digit sets, suggesting digit sets, launching the GUI or API,
+    and performing string rebase operations.
+    """
+    parser = argparse.ArgumentParser(
+        description=(
+            "BaseBender: A tool for rebaseing strings between different "
+            "digit sets (positional number systems)."
+        ),
+        epilog="For more information, refer to the project's README.md.",
+    )
+    parser.add_argument(
+        "input_string",
+        nargs="?",
+        default=None,
+        help=(
+            "The string to be rebased. Required unless --list-digit-sets, "
+            "--suggest-digit-sets, --gui, or --api is used."
+        ),
+    )
+    parser.add_argument(
+        "output_digit_set",
+        nargs="?",
+        default=None,
+        help=(
+            "The target digit set string for the rebase operation. If "
+            "omitted, the input string will be filtered based on the input "
+            "digit set."
+        ),
+    )
+    parser.add_argument(
+        "input_digit_set",
+        nargs="?",
+        default=None,
+        help=(
+            "The source digit set string for the rebase operation. If "
+            "omitted, the input digit set will be dynamically derived from "
+            "the input string."
+        ),
+    )
+    parser.add_argument(
+        "-l",
+        "--list-digit-sets",
+        action="store_true",
+        help=("List all available pre-defined digit sets loaded from configuration files."),
+    )
+    parser.add_argument(
+        "-s",
+        "--suggest-digit-sets",
+        metavar="STRING",
+        help=(
+            "Suggest pre-defined digit sets that are relevant to the "
+            "provided STRING based on its characters."
+        ),
+    )
+    parser.add_argument(
+        "--gui",
+        action="store_true",
+        help="Launch the graphical user interface for interactive rebaseing.",
+    )
+    parser.add_argument(
+        "--api",
+        action="store_true",
+        help=("Start the FastAPI server, providing a web API for rebase operations."),
+    )
+
+    args = parser.parse_args()
+    exit_code = 0
+
+    if args.gui:
+        from basebender.gui.main_window import run_gui
+
+        run_gui()
+    elif args.api:
+        # Ensure the API module is importable from the current directory
+        uvicorn.run("basebender.api.main:APP", host="0.0.0.0", port=8000, reload=True)
+    elif args.list_digit_sets:
+        exit_code = list_digit_sets_cli()
+    elif args.suggest_digit_sets:
+        exit_code = suggest_digit_sets_cli(args.suggest_digit_sets)
+    else:
+        # If no specific action (list, suggest, gui, api) is requested, rebase
+        if args.input_string is None and not (
+            args.list_digit_sets or args.suggest_digit_sets or args.gui or args.api
+        ):
+            parser.error(
+                "input_string is required for rebase when not using "
+                "--list-digit-sets, --suggest-digit-sets, --gui, or --api."
+            )
+        exit_code = perform_rebase_cli(
+            args.input_string, args.output_digit_set, args.input_digit_set
+        )
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

basebender/gui/STRUCTURE.md

@@ -0,0 +1,8 @@
+# `src/gui/` Directory Structure
+
+This directory contains the graphical user interface components.
+
+## Files:
+
+*   [`__init__.py`](src/gui/__init__.py): Initializes the `gui` package.
+*   [`main_window.py`](src/gui/main_window.py): Defines the main window of the GUI application.

basebender/gui/__init__.py

@@ -0,0 +1,3 @@
+"""
+This package provides the graphical user interface for the BaseBender tool.
+"""