letx 0.1.0__py3-none-any.whl

letx/__init__.py

@@ -0,0 +1,23 @@
+"""
+letx - The developer utility toolkit
+Copyright (C) 2026 <Your Name or Organization>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+-------------------------------------------------------------------------
+letx — The developer utility toolkit.
+Debug smarter, fix faster.
+"""
+
+__version__ = "0.1.0"

letx/cli.py

@@ -0,0 +1,69 @@
+"""
+letx.cli
+--------
+Shared CLI dispatcher — each entry_point calls run_module(name).
+Copyright (C) 2026 AMMAAR BAKSHI
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>6
+"""
+import sys
+from argparse import ArgumentParser
+
+from letx.modules import REGISTRY
+from letx.utils.printer import console, error
+
+
+def run_module(module_name: str):
+    """Generic dispatcher. Called by each console_scripts entry point."""
+    module = REGISTRY.get(module_name)
+    if module is None:
+        error(f"Unknown module: [bold]{module_name}[/bold]")
+        sys.exit(1)
+
+    parser = ArgumentParser(
+        prog=module.name,
+        description=module.description,
+    )
+    module.register_args(parser)
+
+    args = parser.parse_args()
+    sys.exit(module.run(args))
+
+
+# ── Individual entry points ───────────────────────────────────────────────────
+
+def letx_debug():
+    run_module("letxDebug")
+
+
+def letx_fix():
+    run_module("letxFix")
+
+
+# ── Global `letx` meta-command ────────────────────────────────────────────────
+
+def letx_main():
+    """
+    `letx` — lists all available tools and their descriptions.
+    """
+    from rich.table import Table
+    e = Table(box=box.ROUNDED, border_style="yellow", show_header=True)
+    table.add_column("Command", style="bold cyan", no_wrap=True)
+    table.add_column("Description", style="white")
+
+    for name, mod in REGISTRY.items():
+        table.add_row(name, mod.description)
+
+    console.print(table)
+    console.print("\n[dim]Run [bold]<command> --help[/bold] for usage details.[/dim]\n");

letx/core/__init__.py

@@ -0,0 +1,26 @@
+"""
+letx - The developer utility toolkit
+Copyright (C) 2026 AMMAAR BAKSHI
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+-------------------------------------------------------------------------
+letx.core
+---------
+Core abstract base classes and logic for the letx toolkit.
+"""
+
+from .base import LetxModule
+
+__all__ = ["LetxModule"]

letx/core/base.py

@@ -0,0 +1,60 @@
+"""
+letx.core.base
+--------------
+Base class for all letx modules.
+Every new module (letxDebug, letxFix, letxLint, etc.) subclasses LetxModule.
+
+Copyright (C) 2026 AMMAAR BAKSHI
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+"""
+from abc import ABC, abstractmethod
+from argparse import ArgumentParser
+
+
+class LetxModule(ABC):
+    """
+    Base class for all letx CLI modules.
+
+    To add a new module:
+        1. Create a file in letx/modules/
+        2. Subclass LetxModule
+        3. Implement name, description, register_args, run
+        4. Register it in letx/modules/__init__.py
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """CLI command name, e.g. 'letxDebug'"""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Short one-liner shown in --help"""
+        ...
+
+    @abstractmethod
+    def register_args(self, parser: ArgumentParser) -> None:
+        """Add module-specific arguments to the parser."""
+        ...
+
+    @abstractmethod
+    def run(self, args) -> int:
+        """
+        Execute the module logic.
+        Return 0 on success, non-zero on failure.
+        """
+        ...

letx/modules/__init__.py

@@ -0,0 +1,30 @@
+"""
+letx - The developer utility toolkit
+Copyright (C) 2026 AMMAAR BAKSHI
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+-------------------------------------------------------------------------
+letx.modules
+------------
+Registry for all available letx modules.
+"""
+
+from letx.modules.debug import DebugModule
+from letx.modules.fix import FixModule
+
+REGISTRY = {
+    "letxDebug": DebugModule(),
+    "letxFix": FixModule(),
+}

letx/modules/debug.py

@@ -0,0 +1,294 @@
+"""
+letx.modules.debug
+------------------
+letxDebug — Smart Python debugger.
+
+Usage:
+    letxDebug file.py          # run and show clean debug output
+    letxDebug -e file.py       # explain the error in plain English
+    letxDebug -s file.py       # suggest a fix/solution
+    letxDebug -a file.py       # explain + solution (all)
+
+Copyright (C) 2026 AMMAAR BAKSHI
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+"""
+import os
+from argparse import ArgumentParser
+
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+from letx.core.base import LetxModule
+from letx.utils.runner import run_file
+from letx.utils.printer import (
+    console, header, section, success, error,
+    warning, info, code_block, divider, tip
+)
+
+# ── Known error explanations ────────────────────────────────────────────────
+
+KNOWN_ERRORS = {
+    "SyntaxError": (
+        "Python couldn't understand your code because of a typo or missing character.",
+        [
+            "Check for missing colons `:` after `if`, `for`, `def`, `class`",
+            "Check for unclosed brackets `(`, `[`, `{`",
+            "Check for mismatched quotes `'` or `\"`",
+        ],
+    ),
+    "IndentationError": (
+        "Your code's indentation (spaces/tabs) is inconsistent.",
+        [
+            "Make sure you use only spaces OR only tabs (not both)",
+            "Each block inside `if`, `for`, `def` must be indented one level",
+            "Don't add extra spaces accidentally",
+        ],
+    ),
+    "NameError": (
+        "You used a variable or function that Python doesn't know about yet.",
+        [
+            "Check the spelling of the variable name",
+            "Make sure you defined the variable before using it",
+            "If it's a function from a module, did you import it?",
+        ],
+    ),
+    "TypeError": (
+        "You performed an operation on the wrong type of value.",
+        [
+            "e.g. adding a string and a number: use `int()` or `str()` to convert",
+            "Check what type your function expects vs what you're passing",
+            "Use `type(x)` to inspect a variable's type",
+        ],
+    ),
+    "ValueError": (
+        "You passed the right type but an invalid value.",
+        [
+            "e.g. `int('hello')` — 'hello' can't become a number",
+            "Check the input data before converting or processing it",
+        ],
+    ),
+    "IndexError": (
+        "You tried to access a list position that doesn't exist.",
+        [
+            "Lists start at index 0, not 1",
+            "Check the length: `len(my_list)` before accessing `my_list[i]`",
+            "The last valid index is `len(my_list) - 1`",
+        ],
+    ),
+    "KeyError": (
+        "You tried to access a dictionary key that doesn't exist.",
+        [
+            "Use `dict.get('key', default)` instead of `dict['key']` to avoid crashes",
+            "Check if the key exists first: `if 'key' in my_dict:`",
+            "Print `my_dict.keys()` to see what keys are available",
+        ],
+    ),
+    "AttributeError": (
+        "You tried to use a method or property that doesn't exist on that object.",
+        [
+            "Check the spelling of the attribute/method",
+            "Use `dir(obj)` to list what methods an object has",
+            "Make sure the object is the type you think it is",
+        ],
+    ),
+    "ImportError": (
+        "Python couldn't find or load the module you're importing.",
+        [
+            "Run `pip install <module-name>` to install missing packages",
+            "Check the spelling of the module name",
+            "Make sure you're in the right virtual environment",
+        ],
+    ),
+    "ModuleNotFoundError": (
+        "The module you're trying to import is not installed.",
+        [
+            "Run: `pip install <module-name>`",
+            "Check if the module name is spelled correctly",
+            "Verify your Python environment has the package",
+        ],
+    ),
+    "ZeroDivisionError": (
+        "Your code tried to divide a number by zero.",
+        [
+            "Add a check before dividing: `if denominator != 0:`",
+            "Use a try/except block to handle it gracefully",
+        ],
+    ),
+    "FileNotFoundError": (
+        "Python looked for a file but couldn't find it at the given path.",
+        [
+            "Double-check the file path and spelling",
+            "Use `os.path.exists(path)` to verify the file is there",
+            "Make sure you're running from the right directory",
+        ],
+    ),
+    "RecursionError": (
+        "Your function called itself too many times — an infinite loop of calls.",
+        [
+            "Make sure your recursive function has a clear base case that stops the recursion",
+            "Check if the base case is actually being reached",
+        ],
+    ),
+    "MemoryError": (
+        "Python ran out of memory trying to run your code.",
+        [
+            "Avoid loading huge files all at once — read in chunks",
+            "Delete large variables with `del x` when no longer needed",
+            "Use generators instead of lists for large data",
+        ],
+    ),
+    "OverflowError": (
+        "A numeric operation produced a result too large for Python to handle.",
+        [
+            "Use Python's `decimal` module for very large precise numbers",
+            "Check your algorithm for unintended exponential growth",
+        ],
+    ),
+    "StopIteration": (
+        "You called `next()` on an iterator that ran out of items.",
+        [
+            "Use a `for` loop instead of manually calling `next()`",
+            "Wrap in try/except StopIteration if you need to handle the end explicitly",
+        ],
+    ),
+    "RuntimeError": (
+        "A general error occurred during execution.",
+        [
+            "Read the full traceback carefully for the specific cause",
+            "Common in async code — make sure you're using `await` correctly",
+        ],
+    ),
+    "PermissionError": (
+        "Your script doesn't have permission to access a file or resource.",
+        [
+            "Check if the file is read-only",
+            "Try running with elevated permissions if appropriate",
+            "Ensure the file isn't open in another program",
+        ],
+    ),
+    "TimeoutError": (
+        "An operation took too long and was cancelled.",
+        [
+            "Add timeout handling with `try/except TimeoutError`",
+            "Check network or I/O calls that might be hanging",
+        ],
+    ),
+}
+
+# ── Module ───────────────────────────────────────────────────────────────────
+
+class DebugModule(LetxModule):
+
+    @property
+    def name(self) -> str:
+        return "letxDebug"
+
+    @property
+    def description(self) -> str:
+        return "Smart Python debugger — run, explain, and fix errors"
+
+    def register_args(self, parser: ArgumentParser) -> None:
+        parser.add_argument("file", help="Python file to debug")
+        mode = parser.add_mutually_exclusive_group()
+        mode.add_argument("-e", "--explain", action="store_true",
+                          help="Explain the error in plain English")
+        mode.add_argument("-s", "--solution", action="store_true",
+                          help="Suggest a solution/fix")
+        mode.add_argument("-a", "--all", dest="all_modes", action="store_true",
+                          help="Explain + solution (everything)")
+
+    def run(self, args) -> int:
+        filepath = args.file
+
+        if not os.path.isfile(filepath):
+            error(f"File not found: [bold]{filepath}[/bold]")
+            return 1
+
+        header("letxDebug", f"Debugging → {filepath}")
+
+        result = run_file(filepath)
+
+        # ── Success path ────────────────────────────────────────────────
+        if not result.has_error:
+            success(f"File ran successfully with exit code [bold green]0[/bold green]")
+            if result.stdout:
+                section("Output", "📤")
+                console.print(result.stdout)
+            return 0
+
+        # ── Base debug output (always shown) ────────────────────────────
+        section("Traceback", "🔴")
+        console.print(f"[dim]{result.traceback}[/dim]")
+        divider()
+
+        if result.error_type and result.error_message:
+            console.print(
+                f"[bold red]{result.error_type}[/bold red]: [white]{result.error_message}[/white]"
+            )
+        if result.error_line:
+            warning(f"Error on line [bold]{result.error_line}[/bold] of [bold]{filepath}[/bold]")
+
+            # Show the relevant source lines
+            try:
+                with open(filepath) as f:
+                    lines = f.readlines()
+                start = max(0, result.error_line - 3)
+                end = min(len(lines), result.error_line + 2)
+                snippet = "".join(lines[start:end])
+                section("Source Context", "📄")
+                code_block(snippet)
+            except Exception:
+                pass
+
+        # ── Explain mode ────────────────────────────────────────────────
+        if args.explain or args.all_modes:
+            self._explain(result)
+
+        # ── Solution mode ───────────────────────────────────────────────
+        if args.solution or args.all_modes:
+            self._solution(result)
+
+        return 1
+
+    def _explain(self, result):
+        section("Error Explanation", "💬")
+        etype = result.error_type or "UnknownError"
+        entry = KNOWN_ERRORS.get(etype)
+
+        if entry:
+            explanation, _ = entry
+            console.print(f"[white]{explanation}[/white]")
+        else:
+            console.print(
+                f"[white]A [bold red]{etype}[/bold red] occurred.\n"
+                f"Message: [italic]{result.error_message}[/italic][/white]"
+            )
+            info("This is an uncommon error — read the traceback carefully.")
+
+    def _solution(self, result):
+        section("Suggested Fix", "🔧")
+        etype = result.error_type or "UnknownError"
+        entry = KNOWN_ERRORS.get(etype)
+
+        if entry:
+            _, hints = entry
+            for i, hint in enumerate(hints, 1):
+                console.print(f"  [bold cyan]{i}.[/bold cyan] {hint}")
+        else:
+            tip(f"Search for `{etype}: {result.error_message}` on Stack Overflow or the Python docs.")
+
+        divider()
+        info("Run [bold yellow]letxDebug -a file.py[/bold yellow] to see both explanation and solution.")