error-translator-cli-v2 1.1.4__tar.gz → 2.0.0__tar.gz

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: error-translator-cli-v2
-Version: 1.1.4
-Summary: A CLI tool that explains Python errors in simple human language.
-Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
+Version: 2.0.0
+Summary: Offline Python traceback translator and error explainer CLI that converts exceptions into clear explanations and actionable fixes.
+Author-email: Gourabananda Datta <gourabanandadatta@zohomail.in>
 License: MIT License
         
         Copyright (c) 2026 Gourabananda Datta
@@ -25,13 +25,14 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Project-URL: Homepage, https://github.com/gourabanandad/error-translator
-Project-URL: Source, https://github.com/gourabanandad/error-translator
-Project-URL: Documentation, https://github.com/gourabanandad/error-translator/tree/master/docs
-Project-URL: Issues, https://github.com/gourabanandad/error-translator/issues
-Project-URL: Changelog, https://github.com/gourabanandad/error-translator/releases
-Project-URL: Contributors, https://github.com/gourabanandad/error-translator/graphs/contributors
-Keywords: python,traceback,cli,debugging,error handling,developer tools
+Project-URL: Homepage, https://github.com/gourabanandad/error-translator-cli-v2
+Project-URL: Source, https://github.com/gourabanandad/error-translator-cli-v2
+Project-URL: Documentation, https://gourabanandad.github.io/error-translator-cli-v2/
+Project-URL: Issues, https://github.com/gourabanandad/error-translator-cli-v2/issues
+Project-URL: Changelog, https://github.com/gourabanandad/error-translator-cli-v2/releases
+Project-URL: Contributors, https://github.com/gourabanandad/error-translator-cli-v2/graphs/contributors
+Project-URL: PyPI, https://pypi.org/project/error-translator-cli-v2/
+Keywords: python,python error translator,traceback translator,python traceback analyzer,python exception explainer,error explainer,error handling,debugging,developer tools,stack-trace,cli,terminal,offline,fastapi,human-readable
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -75,7 +76,7 @@ Dynamic: license-file
 
 <br>
 
-**Error Translator** is a powerful offline engine designed to parse raw Python tracebacks and translate them into crystal-clear explanations with immediately actionable fixes. Built with local-first development workflows in mind, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
+**Error Translator** is an offline Python traceback translator and exception explainer that converts raw errors into crystal-clear explanations and immediately actionable fixes. Built for local-first development workflows, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
 
 If this project saves you debugging time, please consider starring it on GitHub: https://github.com/gourabanandad/error-translator-cli-v2
 
@@ -89,9 +90,11 @@ If this project saves you debugging time, please consider starring it on GitHub:
 ## Key Features
 
 * **CLI-First Architecture**: Seamlessly process scripts, direct error strings, or piped logs via the `explain-error` command.
+* **Professional Rich Terminal UI**: Clean panels, syntax-highlighted code context, structured sections, and improved readability for day-to-day debugging.
 * **Automatic Integration Mode**: Inject the module via `import error_translator.auto` to automatically override `sys.excepthook` for graceful, translated crash reporting.
 * **Extensible API Surfaces**: Integrate natively within Python or expose the core engine over HTTP via the included FastAPI server.
 * **Deterministic Rules Engine**: High-performance, regex-based matching powered by `rules.json` guarantees offline and privacy-first translations.
+* **Optional Native Acceleration**: A C extension matcher (`fast_matcher`) can accelerate rule scanning, with automatic fallback to pure Python when unavailable.
 * **Optional AST Insight Hooks**: Registered handlers can append targeted hints (`ast_insight`) for selected error types.
 
 ## Installation
@@ -129,6 +132,19 @@ Pipe system or Docker logs into the engine:
 cat error.log | explain-error
 ```
 
+Emit structured JSON for scripting and automation:
+```bash
+explain-error --json "NameError: name 'x' is not defined"
+# {"explanation": "...", "fix": "...", "matched_error": "...", "file": "...", "line": "...", "code": "...", "ast_insight": null}
+```
+
+Show an about screen with project metadata and quick usage examples:
+```bash
+explain-error --about
+```
+
+The `--json` flag works with every input mode (`run <script>`, raw string, piped log).
+
 ### 2. Automatic Import Hook
 
 Catch and translate unhandled exceptions globally by importing the module:
@@ -149,7 +165,7 @@ if __name__ == "__main__":
 Start the built-in HTTP server for remote translation services:
 
 ```bash
-uvicorn error_translator.server:app --host 127.0.0.1 --port 8000 --reload
+uvicorn error_translator.api.server:app --host 127.0.0.1 --port 8000 --reload
 ```
 
 Submit a traceback payload via the exposed REST API:
@@ -163,7 +179,20 @@ curl -X POST http://127.0.0.1:8000/translate \
 Additional endpoints:
 
 - `GET /health` returns service status.
-- `GET /` serves the bundled web UI from `error_translator/static/index.html`.
+- `GET /` serves the bundled web UI from `error_translator/api/static/index.html`.
+
+### 4. Optional C Extension Build
+
+The translation engine automatically attempts to import `error_translator.fast_matcher`.
+If it is not built or not available on the platform, Error Translator falls back to the pure Python regex loop with no behavior change.
+
+Build the extension in-place from the repository root:
+
+```bash
+python setup_ext.py build_ext --inplace
+```
+
+This step is optional and intended for local performance optimization.
 
 ## Documentation
 

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0}/README.md

@@ -11,7 +11,7 @@
 
 <br>
 
-**Error Translator** is a powerful offline engine designed to parse raw Python tracebacks and translate them into crystal-clear explanations with immediately actionable fixes. Built with local-first development workflows in mind, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
+**Error Translator** is an offline Python traceback translator and exception explainer that converts raw errors into crystal-clear explanations and immediately actionable fixes. Built for local-first development workflows, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
 
 If this project saves you debugging time, please consider starring it on GitHub: https://github.com/gourabanandad/error-translator-cli-v2
 
@@ -25,9 +25,11 @@ If this project saves you debugging time, please consider starring it on GitHub:
 ## Key Features
 
 * **CLI-First Architecture**: Seamlessly process scripts, direct error strings, or piped logs via the `explain-error` command.
+* **Professional Rich Terminal UI**: Clean panels, syntax-highlighted code context, structured sections, and improved readability for day-to-day debugging.
 * **Automatic Integration Mode**: Inject the module via `import error_translator.auto` to automatically override `sys.excepthook` for graceful, translated crash reporting.
 * **Extensible API Surfaces**: Integrate natively within Python or expose the core engine over HTTP via the included FastAPI server.
 * **Deterministic Rules Engine**: High-performance, regex-based matching powered by `rules.json` guarantees offline and privacy-first translations.
+* **Optional Native Acceleration**: A C extension matcher (`fast_matcher`) can accelerate rule scanning, with automatic fallback to pure Python when unavailable.
 * **Optional AST Insight Hooks**: Registered handlers can append targeted hints (`ast_insight`) for selected error types.
 
 ## Installation
@@ -65,6 +67,19 @@ Pipe system or Docker logs into the engine:
 cat error.log | explain-error
 ```
 
+Emit structured JSON for scripting and automation:
+```bash
+explain-error --json "NameError: name 'x' is not defined"
+# {"explanation": "...", "fix": "...", "matched_error": "...", "file": "...", "line": "...", "code": "...", "ast_insight": null}
+```
+
+Show an about screen with project metadata and quick usage examples:
+```bash
+explain-error --about
+```
+
+The `--json` flag works with every input mode (`run <script>`, raw string, piped log).
+
 ### 2. Automatic Import Hook
 
 Catch and translate unhandled exceptions globally by importing the module:
@@ -85,7 +100,7 @@ if __name__ == "__main__":
 Start the built-in HTTP server for remote translation services:
 
 ```bash
-uvicorn error_translator.server:app --host 127.0.0.1 --port 8000 --reload
+uvicorn error_translator.api.server:app --host 127.0.0.1 --port 8000 --reload
 ```
 
 Submit a traceback payload via the exposed REST API:
@@ -99,7 +114,20 @@ curl -X POST http://127.0.0.1:8000/translate \
 Additional endpoints:
 
 - `GET /health` returns service status.
-- `GET /` serves the bundled web UI from `error_translator/static/index.html`.
+- `GET /` serves the bundled web UI from `error_translator/api/static/index.html`.
+
+### 4. Optional C Extension Build
+
+The translation engine automatically attempts to import `error_translator.fast_matcher`.
+If it is not built or not available on the platform, Error Translator falls back to the pure Python regex loop with no behavior change.
+
+Build the extension in-place from the repository root:
+
+```bash
+python setup_ext.py build_ext --inplace
+```
+
+This step is optional and intended for local performance optimization.
 
 ## Documentation
 

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0}/pyproject.toml

@@ -4,15 +4,31 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "error-translator-cli-v2"
-version = "1.1.4"
-description = "A CLI tool that explains Python errors in simple human language."
+version = "2.0.0"
+description = "Offline Python traceback translator and error explainer CLI that converts exceptions into clear explanations and actionable fixes."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
 authors = [
-    { name = "Gourabananda Datta", email = "gourabanandadatta@zohomail.com" }
+    { name = "Gourabananda Datta", email = "gourabanandadatta@zohomail.in" }
+]
+keywords = [
+    "python",
+    "python error translator",
+    "traceback translator",
+    "python traceback analyzer",
+    "python exception explainer",
+    "error explainer",
+    "error handling",
+    "debugging",
+    "developer tools",
+    "stack-trace",
+    "cli",
+    "terminal",
+    "offline",
+    "fastapi",
+    "human-readable"
 ]
-keywords = ["python", "traceback", "cli", "debugging", "error handling", "developer tools"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
@@ -30,12 +46,13 @@ classifiers = [
 ]
 
 [project.urls]
-"Homepage" = "https://github.com/gourabanandad/error-translator"
-"Source" = "https://github.com/gourabanandad/error-translator"
-"Documentation" = "https://github.com/gourabanandad/error-translator/tree/master/docs"
-"Issues" = "https://github.com/gourabanandad/error-translator/issues"
-"Changelog" = "https://github.com/gourabanandad/error-translator/releases"
-"Contributors" = "https://github.com/gourabanandad/error-translator/graphs/contributors"
+"Homepage" = "https://github.com/gourabanandad/error-translator-cli-v2"
+"Source" = "https://github.com/gourabanandad/error-translator-cli-v2"
+"Documentation" = "https://gourabanandad.github.io/error-translator-cli-v2/"
+"Issues" = "https://github.com/gourabanandad/error-translator-cli-v2/issues"
+"Changelog" = "https://github.com/gourabanandad/error-translator-cli-v2/releases"
+"Contributors" = "https://github.com/gourabanandad/error-translator-cli-v2/graphs/contributors"
+"PyPI" = "https://pypi.org/project/error-translator-cli-v2/"
 
 [project.scripts]
 explain-error = "error_translator.cli:main"
@@ -46,7 +63,11 @@ docs = ["mkdocs>=1.6", "mkdocs-material>=9.7", "pymdown-extensions>=10.0"]
 dev = ["pytest>=8.0", "build>=1.2", "twine>=5.0"]
 
 [tool.setuptools]
+package-dir = {"" = "src"}
 packages = ["error_translator"]
 
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
 [tool.setuptools.package-data]
 error_translator = ["rules.json", "static/*.html", "static/*.css"]

error_translator_cli_v2-2.0.0/src/error_translator/cli.py

@@ -0,0 +1,265 @@
+import json
+import sys
+import argparse
+from .core import translate_error
+from importlib.metadata import version, PackageNotFoundError
+
+# Import Rich UI Components
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+from rich.table import Table
+from rich import box
+
+try:
+    VERSION = version("error-translator-cli-v2")
+except PackageNotFoundError:
+    VERSION = "unknown (not installed via pip)"
+
+# Initialize the global rich console
+console = Console()
+
+
+def _print_title_banner():
+    banner = Text()
+    banner.append("Error Translator CLI\n", style="bold bright_magenta")
+    banner.append("Translate Python tracebacks into clear, actionable guidance.", style="cyan")
+    console.print(
+        Panel(
+            banner,
+            border_style="magenta",
+            padding=(1, 2),
+            expand=False,
+        )
+    )
+
+def print_about():
+    """Prints a polished about view using rich components."""
+    _print_title_banner()
+
+    meta = Table.grid(padding=(0, 1))
+    meta.add_column(style="bold white", justify="right")
+    meta.add_column(style="green")
+    meta.add_row("Version", VERSION)
+    meta.add_row("Author", "Gourabananda Datta")
+    meta.add_row("Repository", "https://github.com/gourabanandad/error-translator-cli-v2")
+    console.print(Panel(meta, title="[bold cyan]Project[/]", border_style="cyan", expand=False))
+
+    features = Text()
+    features.append("• Offline and fast translation\n", style="white")
+    features.append("• Human-readable explanations\n", style="white")
+    features.append("• Actionable fix suggestions\n", style="white")
+    features.append("• Optional AST-level insight", style="white")
+    console.print(Panel(features, title="[bold green]Features[/]", border_style="green", expand=False))
+
+    examples = Text()
+    examples.append("explain-error run your_script.py\n", style="bold cyan")
+    examples.append("explain-error \"TypeError: ...\"\n", style="bold cyan")
+    examples.append("cat error.log | explain-error", style="bold cyan")
+    console.print(Panel(examples, title="[bold yellow]Quick Start[/]", border_style="yellow", expand=False))
+
+
+def print_result(result: dict):
+    """Print translated output in a polished, professional layout."""
+    console.print()
+
+    if result.get("error") and not result.get("matched_error"):
+        message = result.get("message", "An unexpected error occurred.")
+        console.print(
+            Panel(
+                f"[bold red]{message}[/]",
+                title="[bold red]Error[/]",
+                border_style="red",
+                box=box.ROUNDED,
+                expand=False,
+            )
+        )
+        return
+
+    error_title = result.get("matched_error", "Unknown Error")
+    console.print(
+        Panel(
+            f"[bold white]{error_title}[/]",
+            title="[bold red]Detected Error[/]",
+            border_style="red",
+            box=box.ROUNDED,
+            expand=False,
+        )
+    )
+
+    file_name = result.get("file")
+    line_no = result.get("line", "?")
+    if file_name and file_name != "Unknown File":
+        console.print(
+            Panel(
+                f"[yellow]File:[/] {file_name}\n[yellow]Line:[/] {line_no}",
+                title="[bold yellow]Location[/]",
+                border_style="yellow",
+                box=box.ROUNDED,
+                expand=False,
+            )
+        )
+
+    if result.get("code"):
+        try:
+            start_line = int(line_no)
+        except (TypeError, ValueError):
+            start_line = 1
+
+        syntax = Syntax(
+            result["code"],
+            "python",
+            theme="monokai",
+            line_numbers=True,
+            start_line=start_line,
+            word_wrap=True,
+        )
+        console.print(Panel(syntax, title="[bold blue]Code Context[/]", border_style="blue", box=box.ROUNDED))
+
+    explanation = result.get("explanation", "No explanation available.")
+    console.print(
+        Panel(
+            f"[white]{explanation}[/]",
+            title="[bold cyan]Explanation[/]",
+            title_align="left",
+            border_style="cyan",
+            box=box.ROUNDED,
+            expand=False,
+        )
+    )
+
+    fix = result.get("fix", "No suggested fix available.")
+    console.print(
+        Panel(
+            f"[bold green]{fix}[/]",
+            title="[bold green]Suggested Fix[/]",
+            title_align="left",
+            border_style="green",
+            box=box.ROUNDED,
+            expand=False,
+        )
+    )
+
+    if result.get("ast_insight"):
+        console.print(
+            Panel(
+                f"[white]{result['ast_insight']}[/]",
+                title="[bold magenta]AST Insight[/]",
+                title_align="left",
+                border_style="magenta",
+                box=box.ROUNDED,
+                expand=False,
+            )
+        )
+
+
+def print_result_json(result: dict):
+    """Prints the translated error as a single-line JSON object on stdout."""
+    print(json.dumps(result, ensure_ascii=False))
+
+
+def run_script(script_name: str, *, as_json: bool = False):
+    """Run a Python script and translate traceback output if it fails."""
+    import subprocess
+    try:
+        result = subprocess.run(
+            [sys.executable, script_name],
+            capture_output=True,
+            text=True
+        )
+
+        if result.returncode == 0:
+            print(result.stdout, end="")
+        else:
+            if result.stdout:
+                print(result.stdout, end="")
+
+            translation = translate_error(result.stderr)
+            if as_json:
+                print_result_json(translation)
+            else:
+                print_result(translation)
+
+    except FileNotFoundError:
+        if as_json:
+            print(json.dumps({
+                "error": "script_not_found",
+                "message": f"Could not find script '{script_name}'",
+            }))
+        else:
+            console.print(
+                Panel(
+                    f"[bold red]Could not find script '{script_name}'[/]",
+                    title="[bold red]Execution Error[/]",
+                    border_style="red",
+                    box=box.ROUNDED,
+                    expand=False,
+                )
+            )
+    except Exception as exc:
+        if as_json:
+            print(json.dumps({
+                "error": "runtime_failure",
+                "message": str(exc),
+            }))
+        else:
+            console.print(
+                Panel(
+                    f"[bold red]{exc}[/]",
+                    title="[bold red]Runtime Error[/]",
+                    border_style="red",
+                    box=box.ROUNDED,
+                    expand=False,
+                )
+            )
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="explain-error",
+        description="Error Translator — Turn cryptic Python tracebacks into clear, actionable advice.",
+        epilog="""
+Examples:
+  explain-error run my_script.py
+  explain-error "NameError: name 'usr_count' is not defined"
+  cat error.log | explain-error
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    parser.add_argument("-a", "--about", action="store_true", help="Display information about the tool.")
+    parser.add_argument("-v", "--version", action="store_true", help="Show the current version of the tool.")
+    parser.add_argument("--json", action="store_true", dest="as_json", help="Output the translated error as a JSON object.")
+    parser.add_argument("args", nargs="*", help="Positional arguments.")
+
+    parsed_args = parser.parse_args()
+
+    if parsed_args.about:
+        print_about()
+        sys.exit(0)
+    
+    if parsed_args.version:
+        console.print(f"Error Translator CLI Version: [bold green]{VERSION}[/]")
+        sys.exit(0)
+    
+    emit = print_result_json if parsed_args.as_json else print_result
+
+    if not sys.stdin.isatty():
+        error_input = sys.stdin.read()
+        if error_input.strip():
+            emit(translate_error(error_input))
+            return
+
+    if not parsed_args.args:
+        parser.print_help()
+        sys.exit(1)
+
+    if parsed_args.args[0] == "run" and len(parsed_args.args) > 1:
+        script_name = parsed_args.args[1]
+        run_script(script_name, as_json=parsed_args.as_json)
+    else:
+        error_input = " ".join(parsed_args.args)
+        emit(translate_error(error_input))
+
+if __name__ == "__main__":
+    main()

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0/src}/error_translator/core.py

@@ -3,7 +3,14 @@ import os
 import re
 import linecache
 from functools import lru_cache
-from .ast_handlers import AST_REGISTRY
+from .ast.ast_handlers import AST_REGISTRY
+
+# Attempt to load the ultra-fast C extension, fallback to Python if unavailable
+try:
+    from .fast_matcher import match_loop
+    C_EXTENSION_AVAILABLE = True
+except ImportError:
+    C_EXTENSION_AVAILABLE = False
 
 
 @lru_cache(maxsize=1)
@@ -55,27 +62,47 @@ def translate_error(traceback_text: str) -> dict:
         except Exception:
             pass
 
-    for pattern, rule in rules:
-        match = pattern.search(actual_error_line)
-        if match:
-            extracted_values = list(match.groups())
-            fix_text = rule["fix"].format(*extracted_values)
-
-            error_type = actual_error_line.split(":")[0].strip()
-            handler_function = AST_REGISTRY.get(error_type)
-            insight = None
-            if handler_function and file_name != "Unknown File":
-                insight = handler_function(file_name, extracted_values)
-            return {
-                "explanation": rule["explanation"].format(*extracted_values),
-                "fix": fix_text,
-                "ast_insight": insight,
-                "matched_error": actual_error_line,
-                "file": file_name,
-                "line": line_number,
-                "code": code_context,
-            }
-
+    # ==========================================
+    # FAST MATCHING ENGINE (C Extension + Python Fallback)
+    # ==========================================
+    match = None
+    rule = None
+
+    if C_EXTENSION_AVAILABLE:
+        # Execute the C extension (runs at C speed)
+        result = match_loop(actual_error_line, rules)
+        if result:
+            match, rule = result
+    else:
+        # Standard Python fallback loop
+        for pattern, r in rules:
+            m = pattern.search(actual_error_line)
+            if m:
+                match, rule = m, r
+                break
+
+    if match and rule:
+        extracted_values = list(match.groups())
+        fix_text = rule["fix"].format(*extracted_values)
+
+        error_type = actual_error_line.split(":")[0].strip()
+        handler_function = AST_REGISTRY.get(error_type)
+        insight = None
+        
+        if handler_function and file_name != "Unknown File":
+            insight = handler_function(file_name, line_number, extracted_values)
+        
+        return {
+            "explanation": rule["explanation"].format(*extracted_values),
+            "fix": fix_text,
+            "ast_insight": insight,
+            "matched_error": actual_error_line,
+            "file": file_name,
+            "line": line_number,
+            "code": code_context,
+        }
+
+    # Default fallback when no rules match
     return {
         "explanation": default_error["explanation"],
         "fix": default_error["fix"],
@@ -83,4 +110,4 @@ def translate_error(traceback_text: str) -> dict:
         "file": file_name,
         "line": line_number,
         "code": code_context,
-    }
+    }

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0/src}/error_translator_cli_v2.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: error-translator-cli-v2
-Version: 1.1.4
-Summary: A CLI tool that explains Python errors in simple human language.
-Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
+Version: 2.0.0
+Summary: Offline Python traceback translator and error explainer CLI that converts exceptions into clear explanations and actionable fixes.
+Author-email: Gourabananda Datta <gourabanandadatta@zohomail.in>
 License: MIT License
         
         Copyright (c) 2026 Gourabananda Datta
@@ -25,13 +25,14 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Project-URL: Homepage, https://github.com/gourabanandad/error-translator
-Project-URL: Source, https://github.com/gourabanandad/error-translator
-Project-URL: Documentation, https://github.com/gourabanandad/error-translator/tree/master/docs
-Project-URL: Issues, https://github.com/gourabanandad/error-translator/issues
-Project-URL: Changelog, https://github.com/gourabanandad/error-translator/releases
-Project-URL: Contributors, https://github.com/gourabanandad/error-translator/graphs/contributors
-Keywords: python,traceback,cli,debugging,error handling,developer tools
+Project-URL: Homepage, https://github.com/gourabanandad/error-translator-cli-v2
+Project-URL: Source, https://github.com/gourabanandad/error-translator-cli-v2
+Project-URL: Documentation, https://gourabanandad.github.io/error-translator-cli-v2/
+Project-URL: Issues, https://github.com/gourabanandad/error-translator-cli-v2/issues
+Project-URL: Changelog, https://github.com/gourabanandad/error-translator-cli-v2/releases
+Project-URL: Contributors, https://github.com/gourabanandad/error-translator-cli-v2/graphs/contributors
+Project-URL: PyPI, https://pypi.org/project/error-translator-cli-v2/
+Keywords: python,python error translator,traceback translator,python traceback analyzer,python exception explainer,error explainer,error handling,debugging,developer tools,stack-trace,cli,terminal,offline,fastapi,human-readable
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -75,7 +76,7 @@ Dynamic: license-file
 
 <br>
 
-**Error Translator** is a powerful offline engine designed to parse raw Python tracebacks and translate them into crystal-clear explanations with immediately actionable fixes. Built with local-first development workflows in mind, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
+**Error Translator** is an offline Python traceback translator and exception explainer that converts raw errors into crystal-clear explanations and immediately actionable fixes. Built for local-first development workflows, it supports direct CLI usage, an automatic import hook, a programmatic Python API, and a FastAPI integration.
 
 If this project saves you debugging time, please consider starring it on GitHub: https://github.com/gourabanandad/error-translator-cli-v2
 
@@ -89,9 +90,11 @@ If this project saves you debugging time, please consider starring it on GitHub:
 ## Key Features
 
 * **CLI-First Architecture**: Seamlessly process scripts, direct error strings, or piped logs via the `explain-error` command.
+* **Professional Rich Terminal UI**: Clean panels, syntax-highlighted code context, structured sections, and improved readability for day-to-day debugging.
 * **Automatic Integration Mode**: Inject the module via `import error_translator.auto` to automatically override `sys.excepthook` for graceful, translated crash reporting.
 * **Extensible API Surfaces**: Integrate natively within Python or expose the core engine over HTTP via the included FastAPI server.
 * **Deterministic Rules Engine**: High-performance, regex-based matching powered by `rules.json` guarantees offline and privacy-first translations.
+* **Optional Native Acceleration**: A C extension matcher (`fast_matcher`) can accelerate rule scanning, with automatic fallback to pure Python when unavailable.
 * **Optional AST Insight Hooks**: Registered handlers can append targeted hints (`ast_insight`) for selected error types.
 
 ## Installation
@@ -129,6 +132,19 @@ Pipe system or Docker logs into the engine:
 cat error.log | explain-error
 ```
 
+Emit structured JSON for scripting and automation:
+```bash
+explain-error --json "NameError: name 'x' is not defined"
+# {"explanation": "...", "fix": "...", "matched_error": "...", "file": "...", "line": "...", "code": "...", "ast_insight": null}
+```
+
+Show an about screen with project metadata and quick usage examples:
+```bash
+explain-error --about
+```
+
+The `--json` flag works with every input mode (`run <script>`, raw string, piped log).
+
 ### 2. Automatic Import Hook
 
 Catch and translate unhandled exceptions globally by importing the module:
@@ -149,7 +165,7 @@ if __name__ == "__main__":
 Start the built-in HTTP server for remote translation services:
 
 ```bash
-uvicorn error_translator.server:app --host 127.0.0.1 --port 8000 --reload
+uvicorn error_translator.api.server:app --host 127.0.0.1 --port 8000 --reload
 ```
 
 Submit a traceback payload via the exposed REST API:
@@ -163,7 +179,20 @@ curl -X POST http://127.0.0.1:8000/translate \
 Additional endpoints:
 
 - `GET /health` returns service status.
-- `GET /` serves the bundled web UI from `error_translator/static/index.html`.
+- `GET /` serves the bundled web UI from `error_translator/api/static/index.html`.
+
+### 4. Optional C Extension Build
+
+The translation engine automatically attempts to import `error_translator.fast_matcher`.
+If it is not built or not available on the platform, Error Translator falls back to the pure Python regex loop with no behavior change.
+
+Build the extension in-place from the repository root:
+
+```bash
+python setup_ext.py build_ext --inplace
+```
+
+This step is optional and intended for local performance optimization.
 
 ## Documentation
 

error_translator_cli_v2-2.0.0/src/error_translator_cli_v2.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/error_translator/__init__.py
+src/error_translator/auto.py
+src/error_translator/cli.py
+src/error_translator/core.py
+src/error_translator/rules.json
+src/error_translator_cli_v2.egg-info/PKG-INFO
+src/error_translator_cli_v2.egg-info/SOURCES.txt
+src/error_translator_cli_v2.egg-info/dependency_links.txt
+src/error_translator_cli_v2.egg-info/entry_points.txt
+src/error_translator_cli_v2.egg-info/requires.txt
+src/error_translator_cli_v2.egg-info/top_level.txt
+tests/test_core.py

{error_translator_cli_v2-1.1.4 → error_translator_cli_v2-2.0.0}/tests/test_core.py

@@ -147,3 +147,25 @@ def test_regex_extraction_for_supported_errors(mock_traceback, expected_in_expla
     # 2. Prove the Context Engine successfully parsed the file location
     assert result["file"] == "script.py"
     assert result["line"] == "5"
+
+
+def test_print_result_json_emits_valid_json(capsys):
+    """The --json formatter writes a single line of valid JSON containing the result keys."""
+    import json
+    from error_translator.cli import print_result_json
+
+    payload = {
+        "explanation": "x is undefined",
+        "fix": "Define x before use",
+        "matched_error": "NameError: name 'x' is not defined",
+        "file": "Unknown File",
+        "line": "Unknown Line",
+        "code": "",
+        "ast_insight": None,
+    }
+    print_result_json(payload)
+    captured = capsys.readouterr().out
+    # Single line, valid JSON, contains the key fields
+    assert captured.count("\n") == 1
+    parsed = json.loads(captured.strip())
+    assert parsed == payload

error_translator_cli_v2-1.1.4/error_translator/ast_handlers.py

@@ -1,50 +0,0 @@
-import ast
-import difflib
-import os
-
-# --- 1. THE INDIVIDUAL STRATEGIES (PLUGINS) ---
-
-def handle_name_error(file_path: str, extracted_values: list) -> str:
-    """Finds typos for missing variables."""
-    missing_var = extracted_values[0]
-    
-    # ... (Imagine your previous AST parsing code is here) ...
-    # For brevity, let's assume we found the match:
-    closest_match = "maximum_user_connections" # Mocking the AST output
-    
-    if closest_match:
-        return f"Did you mean to type '{closest_match}'?"
-    return ""
-
-def handle_attribute_error(file_path: str, extracted_values: list) -> str:
-    """Finds typos for missing object methods (e.g., .appendd)"""
-    obj_type = extracted_values[0]
-    missing_attr = extracted_values[1]
-    
-    # ... (AST logic to find valid methods for this object) ...
-    closest_match = "append" # Mocking the AST output
-    
-    if closest_match:
-         return f"{obj_type} objects don't have '{missing_attr}'. Did you mean '{closest_match}'?"
-    return ""
-
-def handle_import_error(file_path: str, extracted_values: list) -> str:
-    """ Find typos for missing imports """
-    missing_module = extracted_values[0]
-    
-    # ... (Imagine your previous AST parsing code is here) ...
-    # For brevity, let's assume we found the match:
-    closest_match = "maximum_user_connections" # Mocking the AST output
-    
-    if closest_match:
-        return f"Did you mean to type '{closest_match}'?"
-    return ""
-    
-# --- 2. THE REGISTRY (THE MAGIC ROUTER) ---
-# We map the string name of the error to the function that handles it.
-AST_REGISTRY = {
-    "NameError": handle_name_error,
-    "AttributeError": handle_attribute_error,
-    "ImportError": handle_import_error,
-    # "SyntaxError": handle_syntax_error,
-}

error_translator_cli_v2-1.1.4/error_translator/cli.py

@@ -1,178 +0,0 @@
-import sys
-import argparse
-from .core import translate_error
-from importlib.metadata import version, PackageNotFoundError
-
-try:
-    VERSION = version("error-translator-cli-v2")
-except PackageNotFoundError:
-    VERSION = "unknown (not installed via pip)"  # Fallback version if package metadata is not found
-
-# ANSI Color Codes
-class Colors:
-    RED = '\033[91m'
-    GREEN = '\033[92m'
-    YELLOW = '\033[93m'
-    CYAN = '\033[96m'
-    BOLD = '\033[1m'
-    RESET = '\033[0m'
-    MAGENTA = '\033[95m'
-
-
-def print_about():
-    """Prints the about message for the tool."""
-    about_text = f"""
-ERROR TRANSLATOR CLI
-=====================
-A lightning-fast, offline tool that translates raw Python tracebacks 
-into human-readable explanations with actionable fixes.
-
-Authors: Gourabananda Datta
-Repository: https://github.com/gourabanandad/error-translator-cli-v2
-Usage:
-  1. Run a script and translate its errors:
-        explain-error run your_script.py
-    2. Translate an error message directly:
-        explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
-    3. Pipe an error log:
-        cat error.log | explain-error
-    4. Get help:
-        explain-error --help
-    5. About:
-        explain-error --about
-"""
-    print(f"\033[96m{about_text}\033[0m")
-
-
-def print_result(result: dict):
-    """Prints the translated error to the terminal with colors."""
-    print(f"\n{Colors.RED}{Colors.BOLD} Error Detected:{Colors.RESET}")
-    print(f"{result.get('matched_error', 'N/A')}")
-    
-    if "file" in result:
-        print(f"{Colors.YELLOW} Location: {result['file']} (Line {result['line']}){Colors.RESET}\n")
-        if result.get("code"):
-            print(f"{Colors.RESET}   |")
-            print(f"{Colors.RESET}   |  {Colors.RED}{result['code']}{Colors.RESET}")
-            print(f"{Colors.RESET}   |\n")
-        else:
-            print("\n")
-
-    else:
-        print()
-    
-    print(f"{Colors.CYAN}{Colors.BOLD} Explanation:{Colors.RESET}")
-    print(f"{result['explanation']}\n")
-    
-    print(f"{Colors.GREEN}{Colors.BOLD} Suggested Fix:{Colors.RESET}")
-    print(f"{result['fix']}\n")
-
-    if result.get("ast_insight"):
-        print(f"{Colors.MAGENTA}{Colors.BOLD} AST Insight:{Colors.RESET}")
-        print(f"{result['ast_insight']}\n")
-
-def run_script(script_name: str):
-    """Runs a python script in the background and catches its errors."""
-    import subprocess
-    try:
-        # Run the script using the current Python environment
-        result = subprocess.run(
-            [sys.executable, script_name],
-            capture_output=True,
-            text=True
-        )
-        
-        # If the script ran perfectly (Return Code 0), print standard output
-        if result.returncode == 0:
-            print(result.stdout, end="")
-        
-        # If the script crashed, print whatever succeeded, THEN translate the error
-        else:
-            if result.stdout:
-                print(result.stdout, end="")
-            
-            translation = translate_error(result.stderr)
-            print_result(translation)
-            
-    except FileNotFoundError:
-        print(f"{Colors.RED}Error: Could not find script '{script_name}'{Colors.RESET}")
-
-# Entry point of the program
-def main():
-    parser = argparse.ArgumentParser(
-        prog="explain-error",
-        description="Error Translator — Turn cryptic Python tracebacks into clear, actionable advice.",
-        epilog="""
-Examples:
-  # Run a Python script and translate any unhandled errors
-  explain-error run my_script.py
-
-  # Translate a raw error string directly
-  explain-error "NameError: name 'usr_count' is not defined"
-
-  # Pipe a traceback from a log file or another command
-  cat error.log | explain-error
-
-For more information, visit: https://github.com/gourabanandad/error-translator
-        """,
-        formatter_class=argparse.RawDescriptionHelpFormatter
-    )
-
-    parser.add_argument(
-        "-a",
-        "--about",
-        action="store_true",
-        help="Display information about the tool."
-    )
-    
-    parser.add_argument(
-        "-v",
-        "--version",
-        action="store_true",
-        help="Show the current version of the tool."
-    )
-
-    parser.add_argument(
-        "args",
-        nargs="*",
-        help=(
-            "Positional arguments. Use 'run <script.py>' to execute a Python file, "
-            "or provide an error string to translate. If no arguments are given and "
-            "stdin is not piped, this help message is displayed."
-        )
-    )
-
-    parsed_args = parser.parse_args()
-
-    if parsed_args.about:
-        print_about()
-        sys.exit(0)
-    
-    if parsed_args.version:
-        print(f"Error Translator CLI Version: {Colors.GREEN}{VERSION}{Colors.RESET}")
-        sys.exit(0)
-    
-    # 1. Handle Piped Input (e.g., cat error.log | explain-error)
-    if not sys.stdin.isatty():
-        error_input = sys.stdin.read()
-        if error_input.strip():
-            print_result(translate_error(error_input))
-            return
-
-    # 2. Print help if no arguments and no piped input
-    if not parsed_args.args:
-        parser.print_help()
-        sys.exit(1)
-
-    # 3. Check if the user used the "run" command
-    if parsed_args.args[0] == "run" and len(parsed_args.args) > 1:
-        script_name = parsed_args.args[1]
-        run_script(script_name)
-
-    # 4. Fallback: Treat the input as a raw error string
-    else:
-        error_input = " ".join(parsed_args.args)
-        print_result(translate_error(error_input))
-
-if __name__ == "__main__":
-    main()

error_translator_cli_v2-1.1.4/error_translator/server.py

@@ -1,47 +0,0 @@
-from error_translator.core import translate_error
-from pydantic import BaseModel
-from fastapi import FastAPI
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse
-import os
-
-from importlib.metadata import version, PackageNotFoundError
-
-try:
-    VERSION = version("error-translator-cli-v2")
-except PackageNotFoundError:
-    VERSION = "unknown (not installed via pip)"
-
-app = FastAPI(
-    title="Error translator API",
-    description="An API that translates Python errors into human-readable English.",
-    version=VERSION
-)
-class ErrorRequest(BaseModel):
-    traceback_setting: str
-
-# API endpoint (existing functionality, unchanged)
-@app.post("/translate")
-def translation_endpoint(request: ErrorRequest):
-    translation_result = translate_error(request.traceback_setting)
-    return translation_result
-
-# Serve the web UI at the root
-@app.get("/")
-def read_root():
-    index_path = os.path.join(os.path.dirname(__file__), "static", "index.html")
-    if os.path.exists(index_path):
-        return FileResponse(index_path)
-    return {
-        "message": "Error translation API is running. Web UI not found. Please ensure static/index.html exists."
-    }
-
-# Health check (useful for monitoring)
-@app.get("/health")
-def health_check():
-    return {"status": "ok"}
-
-# Mount static files directory (CSS, etc.)
-static_path = os.path.join(os.path.dirname(__file__), "static")
-if os.path.exists(static_path):
-    app.mount("/static", StaticFiles(directory=static_path), name="static")

error_translator_cli_v2-1.1.4/error_translator/static/index.html

@@ -1,78 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Error Translator</title>
-    <link rel="stylesheet" href="/static/style.css">
-</head>
-<body>
-    <div class="container">
-        <h1>Error Translator</h1>
-        <p class="subtitle">Paste a Python traceback or error message below.</p>
-        
-        <textarea id="errorInput" placeholder="e.g.&#10;Traceback (most recent call last):&#10;  File &quot;app.py&quot;, line 14, in &lt;module&gt;&#10;    total = &quot;Users: &quot; + 42&#10;TypeError: can only concatenate str (not &quot;int&quot;) to str"></textarea>
-        
-        <button id="translateBtn">Translate</button>
-        
-        <div id="result" class="result hidden">
-            <h3>Explanation</h3>
-            <pre id="explanationText"></pre>
-            <h3>Suggested Fix</h3>
-            <pre id="fixText"></pre>
-        </div>
-        
-        <div id="error" class="error hidden"></div>
-    </div>
-
-    <script>
-        const input = document.getElementById('errorInput');
-        const btn = document.getElementById('translateBtn');
-        const resultDiv = document.getElementById('result');
-        const explanationText = document.getElementById('explanationText');
-        const fixText = document.getElementById('fixText');
-        const errorDiv = document.getElementById('error');
-
-        btn.addEventListener('click', async () => {
-            const errorText = input.value.trim();
-            if (!errorText) {
-                showError('Please enter an error message.');
-                return;
-            }
-
-            btn.disabled = true;
-            btn.textContent = 'Translating...';
-            resultDiv.classList.add('hidden');
-            errorDiv.classList.add('hidden');
-
-            try {
-                const response = await fetch('/translate', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ traceback_setting: errorText })
-                });
-
-                const data = await response.json();
-                
-                if (response.ok) {
-                    explanationText.textContent = data.explanation || 'No explanation provided.';
-                    fixText.textContent = data.fix || 'No fix suggested.';
-                    resultDiv.classList.remove('hidden');
-                } else {
-                    showError(data.detail || 'Translation failed.');
-                }
-            } catch (err) {
-                showError('Network error. Is the server running?');
-            } finally {
-                btn.disabled = false;
-                btn.textContent = 'Translate';
-            }
-        });
-
-        function showError(msg) {
-            errorDiv.textContent = msg;
-            errorDiv.classList.remove('hidden');
-        }
-    </script>
-</body>
-</html>

error_translator_cli_v2-1.1.4/error_translator/static/style.css

@@ -1,93 +0,0 @@
-body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
-    max-width: 900px;
-    margin: 40px auto;
-    padding: 0 20px;
-    background-color: #f8f9fa;
-    color: #212529;
-}
-
-.container {
-    background: white;
-    border-radius: 12px;
-    padding: 30px;
-    box-shadow: 0 4px 12px rgba(0,0,0,0.05);
-}
-
-h1 {
-    margin-top: 0;
-    color: #0d6efd;
-}
-
-.subtitle {
-    color: #6c757d;
-    margin-bottom: 20px;
-}
-
-textarea {
-    width: 100%;
-    height: 200px;
-    padding: 15px;
-    font-family: 'Courier New', monospace;
-    font-size: 14px;
-    border: 1px solid #ced4da;
-    border-radius: 8px;
-    resize: vertical;
-    box-sizing: border-box;
-    background-color: #fdfdfd;
-}
-
-button {
-    background-color: #0d6efd;
-    color: white;
-    border: none;
-    padding: 12px 24px;
-    font-size: 16px;
-    border-radius: 6px;
-    cursor: pointer;
-    margin-top: 15px;
-    transition: background-color 0.2s;
-}
-
-button:hover {
-    background-color: #0b5ed7;
-}
-
-button:disabled {
-    background-color: #6c757d;
-    cursor: not-allowed;
-}
-
-.result {
-    margin-top: 30px;
-    border-top: 1px solid #dee2e6;
-    padding-top: 20px;
-}
-
-.result h3 {
-    margin-bottom: 8px;
-    color: #198754;
-}
-
-.result pre {
-    background-color: #f1f3f5;
-    padding: 15px;
-    border-radius: 6px;
-    overflow-x: auto;
-    white-space: pre-wrap;
-    font-family: 'Courier New', monospace;
-    font-size: 14px;
-}
-
-.error {
-    margin-top: 20px;
-    color: #dc3545;
-    background-color: #f8d7da;
-    border: 1px solid #f5c2c7;
-    padding: 12px;
-    border-radius: 6px;
-}
-
-.hidden {
-    display: none;
-}

error_translator_cli_v2-1.1.4/error_translator_cli_v2.egg-info/SOURCES.txt

@@ -1,19 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-error_translator/__init__.py
-error_translator/ast_handlers.py
-error_translator/auto.py
-error_translator/cli.py
-error_translator/core.py
-error_translator/rules.json
-error_translator/server.py
-error_translator/static/index.html
-error_translator/static/style.css
-error_translator_cli_v2.egg-info/PKG-INFO
-error_translator_cli_v2.egg-info/SOURCES.txt
-error_translator_cli_v2.egg-info/dependency_links.txt
-error_translator_cli_v2.egg-info/entry_points.txt
-error_translator_cli_v2.egg-info/requires.txt
-error_translator_cli_v2.egg-info/top_level.txt
-tests/test_core.py