error-translator-cli-v2 1.0.6__tar.gz → 1.0.8__tar.gz

error_translator_cli_v2-1.0.8/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: error-translator-cli-v2
+Version: 1.0.8
+Summary: A CLI tool that explains Python errors in simple human language.
+Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# Error Translator CLI
+
+Error Translator CLI turns Python tracebacks into clear, actionable explanations. It is a local, rule-based tool that reads the final error line, matches it against a curated regex rule set, and returns a structured translation with the original file, line number, code context, and a suggested fix.
+
+## Highlights
+
+- Runs locally with no model inference or external API calls during normal translation.
+- Supports three entry points: automatic crash interception, CLI execution, and direct traceback translation.
+- Extracts file and line information from standard Python tracebacks when available.
+- Includes optional AST-based insight hooks for a few error families.
+- Provides both machine-readable results and colorized terminal output.
+
+## Installation
+
+Install the published package with pip:
+
+```bash
+pip install error-translator-cli-v2
+```
+
+For local development or running the project from source, install the repository dependencies instead:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+### 1. Automatic crash interception
+
+Import `error_translator.auto` at the top of a script to replace Python's default exception hook with the translated output.
+
+This is the project's magic import: once imported, any unhandled exception in that process is intercepted and formatted by the translator before Python prints the default traceback.
+
+```python
+import error_translator.auto
+
+maximum_user_connections = 100
+print(maximum_user_connectons)
+```
+
+Use this when you want the translation to happen automatically without wrapping your code in a custom try/except block.
+
+### 2. CLI execution
+
+Run a script through the CLI and let the tool translate crashes from `stderr`.
+
+```bash
+explain-error run script.py
+```
+
+You can also translate a raw traceback or error string directly:
+
+```bash
+explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
+```
+
+If you want to pipe a saved traceback into the tool, use the shell syntax for your terminal:
+
+```bash
+Get-Content error.log | explain-error
+```
+
+```bash
+cat error.log | explain-error
+```
+
+### 3. Programmatic use
+
+```python
+from error_translator.core import translate_error
+
+result = translate_error(traceback_text)
+print(result["explanation"])
+```
+
+### 4. HTTP API
+
+Start the FastAPI app with Uvicorn:
+
+```bash
+uvicorn error_translator.server:app --reload
+```
+
+`POST /translate` expects JSON in the form:
+
+```json
+{
+	"traceback_setting": "Traceback (most recent call last): ..."
+}
+```
+
+## What the translator returns
+
+The translation engine returns a dictionary with these fields when available:
+
+- `explanation`
+- `fix`
+- `matched_error`
+- `file`
+- `line`
+- `code`
+- `ast_insight`
+
+## Supported errors
+
+The bundled rule set covers many common Python runtime, syntax, indentation, import, OS, encoding, and networking errors. The full list lives in `error_translator/rules.json` and can be expanded over time without changing the runtime engine.
+
+## Project layout
+
+- `error_translator/core.py` loads the rule set and performs the translation.
+- `error_translator/cli.py` provides the `explain-error` command.
+- `error_translator/auto.py` installs the automatic exception hook.
+- `error_translator/server.py` exposes the HTTP API.
+- `error_translator/ast_handlers.py` contains contextual suggestion hooks.
+- `error_translator/rules.json` stores the rule database.
+
+## Development notes
+
+- `builder.py` can generate new rule drafts with Gemini when `GEMINI_API_KEY` is set.
+- `scraper.py` refreshes the scraped exception dataset from the official Python documentation.
+- `tests/test_core.py` contains the current regression coverage for the translation engine.
+
+Built by Gourabananda Datta.

error_translator_cli_v2-1.0.8/README.md

@@ -0,0 +1,124 @@
+# Error Translator CLI
+
+Error Translator CLI turns Python tracebacks into clear, actionable explanations. It is a local, rule-based tool that reads the final error line, matches it against a curated regex rule set, and returns a structured translation with the original file, line number, code context, and a suggested fix.
+
+## Highlights
+
+- Runs locally with no model inference or external API calls during normal translation.
+- Supports three entry points: automatic crash interception, CLI execution, and direct traceback translation.
+- Extracts file and line information from standard Python tracebacks when available.
+- Includes optional AST-based insight hooks for a few error families.
+- Provides both machine-readable results and colorized terminal output.
+
+## Installation
+
+Install the published package with pip:
+
+```bash
+pip install error-translator-cli-v2
+```
+
+For local development or running the project from source, install the repository dependencies instead:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+### 1. Automatic crash interception
+
+Import `error_translator.auto` at the top of a script to replace Python's default exception hook with the translated output.
+
+This is the project's magic import: once imported, any unhandled exception in that process is intercepted and formatted by the translator before Python prints the default traceback.
+
+```python
+import error_translator.auto
+
+maximum_user_connections = 100
+print(maximum_user_connectons)
+```
+
+Use this when you want the translation to happen automatically without wrapping your code in a custom try/except block.
+
+### 2. CLI execution
+
+Run a script through the CLI and let the tool translate crashes from `stderr`.
+
+```bash
+explain-error run script.py
+```
+
+You can also translate a raw traceback or error string directly:
+
+```bash
+explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
+```
+
+If you want to pipe a saved traceback into the tool, use the shell syntax for your terminal:
+
+```bash
+Get-Content error.log | explain-error
+```
+
+```bash
+cat error.log | explain-error
+```
+
+### 3. Programmatic use
+
+```python
+from error_translator.core import translate_error
+
+result = translate_error(traceback_text)
+print(result["explanation"])
+```
+
+### 4. HTTP API
+
+Start the FastAPI app with Uvicorn:
+
+```bash
+uvicorn error_translator.server:app --reload
+```
+
+`POST /translate` expects JSON in the form:
+
+```json
+{
+	"traceback_setting": "Traceback (most recent call last): ..."
+}
+```
+
+## What the translator returns
+
+The translation engine returns a dictionary with these fields when available:
+
+- `explanation`
+- `fix`
+- `matched_error`
+- `file`
+- `line`
+- `code`
+- `ast_insight`
+
+## Supported errors
+
+The bundled rule set covers many common Python runtime, syntax, indentation, import, OS, encoding, and networking errors. The full list lives in `error_translator/rules.json` and can be expanded over time without changing the runtime engine.
+
+## Project layout
+
+- `error_translator/core.py` loads the rule set and performs the translation.
+- `error_translator/cli.py` provides the `explain-error` command.
+- `error_translator/auto.py` installs the automatic exception hook.
+- `error_translator/server.py` exposes the HTTP API.
+- `error_translator/ast_handlers.py` contains contextual suggestion hooks.
+- `error_translator/rules.json` stores the rule database.
+
+## Development notes
+
+- `builder.py` can generate new rule drafts with Gemini when `GEMINI_API_KEY` is set.
+- `scraper.py` refreshes the scraped exception dataset from the official Python documentation.
+- `tests/test_core.py` contains the current regression coverage for the translation engine.
+
+Built by Gourabananda Datta.

{error_translator_cli_v2-1.0.6 → error_translator_cli_v2-1.0.8}/error_translator/core.py

@@ -1,50 +1,62 @@
 import json
 import os
+import re
+import linecache
+from functools import lru_cache
 from .ast_handlers import AST_REGISTRY
 
+
+@lru_cache(maxsize=1)
 def load_rules():
-    """Loads the error rules from the JSON file."""
-    # Find the absolute path to the json file next to this script
+    """Load the error rules from disk once and cache them."""
     current_dir = os.path.dirname(os.path.abspath(__file__))
-    json_path = os.path.join(current_dir, 'rules.json')
-    
-    with open(json_path, 'r') as file:
+    json_path = os.path.join(current_dir, "rules.json")
+
+    with open(json_path, "r", encoding="utf-8") as file:
         return json.load(file)
 
+
+@lru_cache(maxsize=1)
+def compiled_rules():
+    """Compile regex patterns once to avoid repeated work per translation."""
+    data = load_rules()
+    compiled = []
+    for rule in data["rules"]:
+        compiled.append((re.compile(rule["pattern"]), rule))
+    return compiled
+
+
+def _extract_location(traceback_text: str) -> tuple[str, str]:
+    location_match = re.search(r'File\s+[\'"]?(.*?)[\'"]?,\s+line\s+(\d+)', traceback_text)
+    if not location_match:
+        return "Unknown File", "Unknown Line"
+    return location_match.group(1), location_match.group(2)
+
+
 def translate_error(traceback_text: str) -> dict:
-    import re
-    import linecache  # <-- NEW: Lazy import the linecache module
-    
     data = load_rules()
-    rules = data["rules"]
+    rules = compiled_rules()
     default_error = data["default"]
 
-    lines = [line.strip() for line in traceback_text.strip().split('\n') if line.strip()]
+    lines = [line.strip() for line in traceback_text.strip().split("\n") if line.strip()]
     if not lines:
         return {"explanation": "No error text provided.", "fix": "Provide a valid Python error."}
-    
+
     actual_error_line = lines[-1]
 
-    location_match = re.search(r'File\s+[\'"]?(.*?)[\'"]?,\s+line\s+(\d+)', traceback_text)
-    file_name = location_match.group(1) if location_match else "Unknown File"
-    line_number = location_match.group(2) if location_match else "Unknown Line"
+    file_name, line_number = _extract_location(traceback_text)
 
-    # --- NEW CONTEXT ENGINE LOGIC ---
     code_context = ""
     if file_name != "Unknown File" and line_number != "Unknown Line":
         try:
-            # linecache safely fetches the exact line of code as a string
             raw_line = linecache.getline(file_name, int(line_number))
             if raw_line:
-                code_context = raw_line.strip() # Remove extra spaces/newlines
+                code_context = raw_line.strip()
         except Exception:
-            pass # If the file can't be read for any reason, fail silently
-    # --------------------------------
+            pass
 
-    for rule in rules:
-        pattern = re.compile(rule["pattern"])
+    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)
@@ -61,7 +73,7 @@ def translate_error(traceback_text: str) -> dict:
                 "matched_error": actual_error_line,
                 "file": file_name,
                 "line": line_number,
-                "code": code_context 
+                "code": code_context,
             }
 
     return {
@@ -70,5 +82,5 @@ def translate_error(traceback_text: str) -> dict:
         "matched_error": actual_error_line,
         "file": file_name,
         "line": line_number,
-        "code": code_context      
-    }
+        "code": code_context,
+    }

error_translator_cli_v2-1.0.8/error_translator_cli_v2.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: error-translator-cli-v2
+Version: 1.0.8
+Summary: A CLI tool that explains Python errors in simple human language.
+Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# Error Translator CLI
+
+Error Translator CLI turns Python tracebacks into clear, actionable explanations. It is a local, rule-based tool that reads the final error line, matches it against a curated regex rule set, and returns a structured translation with the original file, line number, code context, and a suggested fix.
+
+## Highlights
+
+- Runs locally with no model inference or external API calls during normal translation.
+- Supports three entry points: automatic crash interception, CLI execution, and direct traceback translation.
+- Extracts file and line information from standard Python tracebacks when available.
+- Includes optional AST-based insight hooks for a few error families.
+- Provides both machine-readable results and colorized terminal output.
+
+## Installation
+
+Install the published package with pip:
+
+```bash
+pip install error-translator-cli-v2
+```
+
+For local development or running the project from source, install the repository dependencies instead:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+### 1. Automatic crash interception
+
+Import `error_translator.auto` at the top of a script to replace Python's default exception hook with the translated output.
+
+This is the project's magic import: once imported, any unhandled exception in that process is intercepted and formatted by the translator before Python prints the default traceback.
+
+```python
+import error_translator.auto
+
+maximum_user_connections = 100
+print(maximum_user_connectons)
+```
+
+Use this when you want the translation to happen automatically without wrapping your code in a custom try/except block.
+
+### 2. CLI execution
+
+Run a script through the CLI and let the tool translate crashes from `stderr`.
+
+```bash
+explain-error run script.py
+```
+
+You can also translate a raw traceback or error string directly:
+
+```bash
+explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
+```
+
+If you want to pipe a saved traceback into the tool, use the shell syntax for your terminal:
+
+```bash
+Get-Content error.log | explain-error
+```
+
+```bash
+cat error.log | explain-error
+```
+
+### 3. Programmatic use
+
+```python
+from error_translator.core import translate_error
+
+result = translate_error(traceback_text)
+print(result["explanation"])
+```
+
+### 4. HTTP API
+
+Start the FastAPI app with Uvicorn:
+
+```bash
+uvicorn error_translator.server:app --reload
+```
+
+`POST /translate` expects JSON in the form:
+
+```json
+{
+	"traceback_setting": "Traceback (most recent call last): ..."
+}
+```
+
+## What the translator returns
+
+The translation engine returns a dictionary with these fields when available:
+
+- `explanation`
+- `fix`
+- `matched_error`
+- `file`
+- `line`
+- `code`
+- `ast_insight`
+
+## Supported errors
+
+The bundled rule set covers many common Python runtime, syntax, indentation, import, OS, encoding, and networking errors. The full list lives in `error_translator/rules.json` and can be expanded over time without changing the runtime engine.
+
+## Project layout
+
+- `error_translator/core.py` loads the rule set and performs the translation.
+- `error_translator/cli.py` provides the `explain-error` command.
+- `error_translator/auto.py` installs the automatic exception hook.
+- `error_translator/server.py` exposes the HTTP API.
+- `error_translator/ast_handlers.py` contains contextual suggestion hooks.
+- `error_translator/rules.json` stores the rule database.
+
+## Development notes
+
+- `builder.py` can generate new rule drafts with Gemini when `GEMINI_API_KEY` is set.
+- `scraper.py` refreshes the scraped exception dataset from the official Python documentation.
+- `tests/test_core.py` contains the current regression coverage for the translation engine.
+
+Built by Gourabananda Datta.

{error_translator_cli_v2-1.0.6 → error_translator_cli_v2-1.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "error-translator-cli-v2"
-version = "1.0.6"
+version = "1.0.8"
 description = "A CLI tool that explains Python errors in simple human language."
 readme = "README.md"
 requires-python = ">=3.7"

{error_translator_cli_v2-1.0.6 → error_translator_cli_v2-1.0.8}/tests/test_core.py

@@ -1,5 +1,5 @@
 import pytest
-from error_translator.core import translate_error
+from error_translator.core import translate_error, load_rules, compiled_rules
 
 # --- 1. EDGE CASE TESTS ---
 
@@ -35,6 +35,24 @@ def test_unknown_error_fallback():
     assert result["matched_error"] == "Something completely random went wrong here."
 
 
+def test_empty_input_returns_helpful_message():
+    result = translate_error("   \n   ")
+    assert result["explanation"] == "No error text provided."
+    assert result["fix"] == "Provide a valid Python error."
+
+
+def test_rule_loading_is_cached():
+    first = load_rules()
+    second = load_rules()
+    assert first is second
+
+
+def test_compiled_rules_are_cached():
+    first = compiled_rules()
+    second = compiled_rules()
+    assert first is second
+
+
 # --- 2. THE PARAMETERIZED ENGINE FOR ALL ERRORS ---
 
 @pytest.mark.parametrize("mock_traceback, expected_in_explanation", [
@@ -128,4 +146,4 @@ 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"
+    assert result["line"] == "5"

error_translator_cli_v2-1.0.6/PKG-INFO

@@ -1,78 +0,0 @@
-Metadata-Version: 2.4
-Name: error-translator-cli-v2
-Version: 1.0.6
-Summary: A CLI tool that explains Python errors in simple human language.
-Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-
-# Error Translator CLI
-
-## Overview
-A lightweight, rule-based command-line tool designed to translate confusing Python traceback errors into plain, human-readable English and suggest actionable fixes.
-
-## Key Features
-- **No AI or LLMs Required:** Runs entirely locally using fast, regex-based pattern matching.
-- **Beginner Friendly:** Explains the root cause of errors in simple English terminology, making debugging more approachable.
-- **Actionable Guidance:** Provides practical, suggested fixes tailored to your specific code context.
-- **Pinpoint Accuracy:** Extracts and highlights the exact file name and line number where the code encountered an issue.
-- **Improved Readability:** Utilizes well-formatted, color-coded terminal output to make reading errors easier.
-
-## Installation
-You can install this tool globally on your machine using pip:
-```bash
-pip install error-translator-cli-v2
-```
-
-## Quick Start Guide
-You can use the Error Translator in three distinct ways, depending on your preferred workflow:
-
-### 1. Magic Import (Recommended)
-Simply add this single import statement at the top of your Python script. If your script crashes, the tool will automatically intercept and translate the error.
-
-```python
-import error_translator.auto
-
-# Your normal code...
-math_is_broken = 10 / 0  # This crash will be automatically intercepted and translated
-```
-
-### 2. Run Scripts via CLI
-You can execute your Python files directly through the provided CLI tool. It will run your program normally and intercept any crashes if they occur.
-
-```bash
-explain-error run script.py
-```
-
-### 3. Translate Raw Error Strings
-You can also pass raw error messages directly as a string or pipe them from another command.
-
-**Pass directly:**
-```bash
-explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
-```
-
-**Pipe from a file:**
-```bash
-cat error.log | explain-error
-```
-
-## Supported Errors
-Currently, the tool can accurately diagnose and explain the following Python errors:
-- NameError
-- TypeError
-- IndexError
-- KeyError
-- ZeroDivisionError
-- ModuleNotFoundError
-- AttributeError
-
-*Note: More error definitions are actively being added to the database.*
-
-## Cloud API
-This tool includes a built-in FastAPI server so you can integrate the translation engine into your own web apps or VS Code extensions.
-```bash
-uvicorn error_translator.server:app --reload
-```
----
-Built by Gourabananda Datta.

error_translator_cli_v2-1.0.6/README.md

@@ -1,70 +0,0 @@
-# Error Translator CLI
-
-## Overview
-A lightweight, rule-based command-line tool designed to translate confusing Python traceback errors into plain, human-readable English and suggest actionable fixes.
-
-## Key Features
-- **No AI or LLMs Required:** Runs entirely locally using fast, regex-based pattern matching.
-- **Beginner Friendly:** Explains the root cause of errors in simple English terminology, making debugging more approachable.
-- **Actionable Guidance:** Provides practical, suggested fixes tailored to your specific code context.
-- **Pinpoint Accuracy:** Extracts and highlights the exact file name and line number where the code encountered an issue.
-- **Improved Readability:** Utilizes well-formatted, color-coded terminal output to make reading errors easier.
-
-## Installation
-You can install this tool globally on your machine using pip:
-```bash
-pip install error-translator-cli-v2
-```
-
-## Quick Start Guide
-You can use the Error Translator in three distinct ways, depending on your preferred workflow:
-
-### 1. Magic Import (Recommended)
-Simply add this single import statement at the top of your Python script. If your script crashes, the tool will automatically intercept and translate the error.
-
-```python
-import error_translator.auto
-
-# Your normal code...
-math_is_broken = 10 / 0  # This crash will be automatically intercepted and translated
-```
-
-### 2. Run Scripts via CLI
-You can execute your Python files directly through the provided CLI tool. It will run your program normally and intercept any crashes if they occur.
-
-```bash
-explain-error run script.py
-```
-
-### 3. Translate Raw Error Strings
-You can also pass raw error messages directly as a string or pipe them from another command.
-
-**Pass directly:**
-```bash
-explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
-```
-
-**Pipe from a file:**
-```bash
-cat error.log | explain-error
-```
-
-## Supported Errors
-Currently, the tool can accurately diagnose and explain the following Python errors:
-- NameError
-- TypeError
-- IndexError
-- KeyError
-- ZeroDivisionError
-- ModuleNotFoundError
-- AttributeError
-
-*Note: More error definitions are actively being added to the database.*
-
-## Cloud API
-This tool includes a built-in FastAPI server so you can integrate the translation engine into your own web apps or VS Code extensions.
-```bash
-uvicorn error_translator.server:app --reload
-```
----
-Built by Gourabananda Datta.

error_translator_cli_v2-1.0.6/error_translator_cli_v2.egg-info/PKG-INFO

@@ -1,78 +0,0 @@
-Metadata-Version: 2.4
-Name: error-translator-cli-v2
-Version: 1.0.6
-Summary: A CLI tool that explains Python errors in simple human language.
-Author-email: Gourabananda Datta <gourabanandadatta@zohomail.com>
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-
-# Error Translator CLI
-
-## Overview
-A lightweight, rule-based command-line tool designed to translate confusing Python traceback errors into plain, human-readable English and suggest actionable fixes.
-
-## Key Features
-- **No AI or LLMs Required:** Runs entirely locally using fast, regex-based pattern matching.
-- **Beginner Friendly:** Explains the root cause of errors in simple English terminology, making debugging more approachable.
-- **Actionable Guidance:** Provides practical, suggested fixes tailored to your specific code context.
-- **Pinpoint Accuracy:** Extracts and highlights the exact file name and line number where the code encountered an issue.
-- **Improved Readability:** Utilizes well-formatted, color-coded terminal output to make reading errors easier.
-
-## Installation
-You can install this tool globally on your machine using pip:
-```bash
-pip install error-translator-cli-v2
-```
-
-## Quick Start Guide
-You can use the Error Translator in three distinct ways, depending on your preferred workflow:
-
-### 1. Magic Import (Recommended)
-Simply add this single import statement at the top of your Python script. If your script crashes, the tool will automatically intercept and translate the error.
-
-```python
-import error_translator.auto
-
-# Your normal code...
-math_is_broken = 10 / 0  # This crash will be automatically intercepted and translated
-```
-
-### 2. Run Scripts via CLI
-You can execute your Python files directly through the provided CLI tool. It will run your program normally and intercept any crashes if they occur.
-
-```bash
-explain-error run script.py
-```
-
-### 3. Translate Raw Error Strings
-You can also pass raw error messages directly as a string or pipe them from another command.
-
-**Pass directly:**
-```bash
-explain-error "TypeError: unsupported operand type(s) for +: 'int' and 'str'"
-```
-
-**Pipe from a file:**
-```bash
-cat error.log | explain-error
-```
-
-## Supported Errors
-Currently, the tool can accurately diagnose and explain the following Python errors:
-- NameError
-- TypeError
-- IndexError
-- KeyError
-- ZeroDivisionError
-- ModuleNotFoundError
-- AttributeError
-
-*Note: More error definitions are actively being added to the database.*
-
-## Cloud API
-This tool includes a built-in FastAPI server so you can integrate the translation engine into your own web apps or VS Code extensions.
-```bash
-uvicorn error_translator.server:app --reload
-```
----
-Built by Gourabananda Datta.