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

error_translator_cli_v2-1.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gourabananda Datta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

error_translator_cli_v2-1.1.4/PKG-INFO

@@ -0,0 +1,178 @@
+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>
+License: MIT License
+        
+        Copyright (c) 2026 Gourabananda Datta
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        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
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: pydantic>=2.6; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.7; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Error Translator
+
+<div align="left">
+  <a href="https://pypi.org/project/error-translator-cli-v2/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/error-translator-cli-v2.svg"></a>
+  <img alt="Python 3.9+" src="https://img.shields.io/badge/python-3.9%2B-blue.svg">
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/gourabanandad/error-translator-cli-v2?style=social"></a>
+  <a href="https://pypi.org/project/error-translator-cli-v2/"><img alt="PyPI Downloads" src="https://img.shields.io/pypi/dm/error-translator-cli-v2"></a>
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2"><img alt="License" src="https://img.shields.io/github/license/gourabanandad/error-translator-cli-v2.svg"></a>
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2/actions/workflows/ci.yml"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/gourabanandad/error-translator-cli-v2/ci.yml?branch=master&label=build"></a>
+</div>
+
+<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.
+
+If this project saves you debugging time, please consider starring it on GitHub: https://github.com/gourabanandad/error-translator-cli-v2
+
+## Why Developers Like It
+
+* **Fast Feedback Loop**: Turn stack traces into direct next actions in seconds.
+* **Works Offline**: No telemetry dependency for core translation behavior.
+* **Beginner-Friendly Output**: Explanations are clear enough for learners, practical enough for teams.
+* **Multiple Entry Points**: CLI, import hook, Python API, and FastAPI all share one deterministic engine.
+
+## Key Features
+
+* **CLI-First Architecture**: Seamlessly process scripts, direct error strings, or piped logs via the `explain-error` command.
+* **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 AST Insight Hooks**: Registered handlers can append targeted hints (`ast_insight`) for selected error types.
+
+## Installation
+
+Python requirement: **3.9 or newer**.
+
+Install the latest stable release directly from PyPI:
+
+```bash
+pip install error-translator-cli-v2
+```
+
+Verify the installation:
+
+```bash
+explain-error --version
+```
+
+## Usage Guide
+
+### 1. Command-Line Interface (CLI)
+
+Run a Python script and catch any unhandled exceptions:
+```bash
+explain-error run script.py
+```
+
+Provide an error string directly:
+```bash
+explain-error "NameError: name 'usr_count' is not defined"
+```
+
+Pipe system or Docker logs into the engine:
+```bash
+cat error.log | explain-error
+```
+
+### 2. Automatic Import Hook
+
+Catch and translate unhandled exceptions globally by importing the module:
+
+```python
+import error_translator.auto
+
+def main():
+    # This TypeError will automatically trigger the error translator
+    total = "Users: " + 42
+
+if __name__ == "__main__":
+    main()
+```
+
+### 3. FastAPI Service
+
+Start the built-in HTTP server for remote translation services:
+
+```bash
+uvicorn error_translator.server:app --host 127.0.0.1 --port 8000 --reload
+```
+
+Submit a traceback payload via the exposed REST API:
+
+```bash
+curl -X POST http://127.0.0.1:8000/translate \
+  -H "Content-Type: application/json" \
+  -d "{\"traceback_setting\":\"Traceback (most recent call last):\\n  File 'app.py', line 14, in <module>\\n    total = 'Users: ' + 42\\nTypeError: can only concatenate str (not 'int') to str\"}"
+```
+
+Additional endpoints:
+
+- `GET /health` returns service status.
+- `GET /` serves the bundled web UI from `error_translator/static/index.html`.
+
+## Documentation
+
+Detailed documentation is located in the [`docs/`](docs/) directory:
+
+- [**Real-World Examples**](docs/examples.md): Practical demonstrations comparing raw tracebacks with their translated counterparts.
+- [**Architecture & Internals**](docs/ARCHITECTURE.md): Comprehensive teardown of the regex engine, AST integration, and internal design philosophy.
+- [**Contributing Guidelines**](docs/CONTRIBUTING.md): Standards, PR checklists, and instructions for utilizing our AI-Powered Rule Builder.
+
+## Maintainers
+
+This project is actively developed and maintained by **Gourabananda Datta** alongside our open-source contributors.

error_translator_cli_v2-1.1.4/README.md

@@ -0,0 +1,114 @@
+# Error Translator
+
+<div align="left">
+  <a href="https://pypi.org/project/error-translator-cli-v2/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/error-translator-cli-v2.svg"></a>
+  <img alt="Python 3.9+" src="https://img.shields.io/badge/python-3.9%2B-blue.svg">
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/gourabanandad/error-translator-cli-v2?style=social"></a>
+  <a href="https://pypi.org/project/error-translator-cli-v2/"><img alt="PyPI Downloads" src="https://img.shields.io/pypi/dm/error-translator-cli-v2"></a>
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2"><img alt="License" src="https://img.shields.io/github/license/gourabanandad/error-translator-cli-v2.svg"></a>
+  <a href="https://github.com/gourabanandad/error-translator-cli-v2/actions/workflows/ci.yml"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/gourabanandad/error-translator-cli-v2/ci.yml?branch=master&label=build"></a>
+</div>
+
+<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.
+
+If this project saves you debugging time, please consider starring it on GitHub: https://github.com/gourabanandad/error-translator-cli-v2
+
+## Why Developers Like It
+
+* **Fast Feedback Loop**: Turn stack traces into direct next actions in seconds.
+* **Works Offline**: No telemetry dependency for core translation behavior.
+* **Beginner-Friendly Output**: Explanations are clear enough for learners, practical enough for teams.
+* **Multiple Entry Points**: CLI, import hook, Python API, and FastAPI all share one deterministic engine.
+
+## Key Features
+
+* **CLI-First Architecture**: Seamlessly process scripts, direct error strings, or piped logs via the `explain-error` command.
+* **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 AST Insight Hooks**: Registered handlers can append targeted hints (`ast_insight`) for selected error types.
+
+## Installation
+
+Python requirement: **3.9 or newer**.
+
+Install the latest stable release directly from PyPI:
+
+```bash
+pip install error-translator-cli-v2
+```
+
+Verify the installation:
+
+```bash
+explain-error --version
+```
+
+## Usage Guide
+
+### 1. Command-Line Interface (CLI)
+
+Run a Python script and catch any unhandled exceptions:
+```bash
+explain-error run script.py
+```
+
+Provide an error string directly:
+```bash
+explain-error "NameError: name 'usr_count' is not defined"
+```
+
+Pipe system or Docker logs into the engine:
+```bash
+cat error.log | explain-error
+```
+
+### 2. Automatic Import Hook
+
+Catch and translate unhandled exceptions globally by importing the module:
+
+```python
+import error_translator.auto
+
+def main():
+    # This TypeError will automatically trigger the error translator
+    total = "Users: " + 42
+
+if __name__ == "__main__":
+    main()
+```
+
+### 3. FastAPI Service
+
+Start the built-in HTTP server for remote translation services:
+
+```bash
+uvicorn error_translator.server:app --host 127.0.0.1 --port 8000 --reload
+```
+
+Submit a traceback payload via the exposed REST API:
+
+```bash
+curl -X POST http://127.0.0.1:8000/translate \
+  -H "Content-Type: application/json" \
+  -d "{\"traceback_setting\":\"Traceback (most recent call last):\\n  File 'app.py', line 14, in <module>\\n    total = 'Users: ' + 42\\nTypeError: can only concatenate str (not 'int') to str\"}"
+```
+
+Additional endpoints:
+
+- `GET /health` returns service status.
+- `GET /` serves the bundled web UI from `error_translator/static/index.html`.
+
+## Documentation
+
+Detailed documentation is located in the [`docs/`](docs/) directory:
+
+- [**Real-World Examples**](docs/examples.md): Practical demonstrations comparing raw tracebacks with their translated counterparts.
+- [**Architecture & Internals**](docs/ARCHITECTURE.md): Comprehensive teardown of the regex engine, AST integration, and internal design philosophy.
+- [**Contributing Guidelines**](docs/CONTRIBUTING.md): Standards, PR checklists, and instructions for utilizing our AI-Powered Rule Builder.
+
+## Maintainers
+
+This project is actively developed and maintained by **Gourabananda Datta** alongside our open-source contributors.

{error_translator_cli_v2-1.1.3 → error_translator_cli_v2-1.1.4}/error_translator/cli.py

@@ -101,9 +101,21 @@ def run_script(script_name: str):
 def main():
     parser = argparse.ArgumentParser(
         prog="explain-error",
-        description="Translate Python error messages into simple English.",
-        epilog="Examples:\n  explain-error run script.py\n  explain-error \"NameError: name 'x' is not defined\"\n  cat error.log | explain-error",
-        formatter_class=argparse.RawTextHelpFormatter
+        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(
@@ -119,11 +131,15 @@ def main():
         action="store_true",
         help="Show the current version of the tool."
     )
-    # Allow multiple arguments so we can accept "run script.py" or a long error string
+
     parser.add_argument(
-        "args", 
-        nargs="*", 
-        help="Use 'run <script.py>' to execute a file, or pass an error string."
+        "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()
@@ -143,23 +159,20 @@ def main():
             print_result(translate_error(error_input))
             return
 
-    # 2. Print help if no arguments
+    # 2. Print help if no arguments and no piped input
     if not parsed_args.args:
         parser.print_help()
         sys.exit(1)
 
-    if parsed_args.args:
-        # 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))
+    # 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:
-        parser.print_help()
-        sys.exit(1)
+        error_input = " ".join(parsed_args.args)
+        print_result(translate_error(error_input))
+
 if __name__ == "__main__":
-    main()
+    main()