clarix 0.0.2__tar.gz

clarix-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kane Bean
+
+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.

clarix-0.0.2/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: clarix
+Version: 0.0.2
+Summary: A smart Python error explainer with rich UI and structured insights
+Author: Kane
+License: MIT
+Keywords: python,debugging,error-explainer,rich,cli,developer-tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+clarix
+------
+
+clarix is a lightweight Python module for explaining and analyzing runtime errors.
+
+Features:
+- Basic error explanation interface
+- Simple API for integration into projects
+- Lightweight and dependency-free design
+
+Installation:
+- pip install clarix
+
+Usage:
+- import clarix
+- clarix.enable()
+
+Current Status:
+- Early development version (0.0.1)
+- Core functionality under expansion
+
+Future Plans:
+- Detailed error categorization
+- Improved explanation engine
+- Support for advanced debugging insights

clarix-0.0.2/README.md

@@ -0,0 +1,25 @@
+clarix
+------
+
+clarix is a lightweight Python module for explaining and analyzing runtime errors.
+
+Features:
+- Basic error explanation interface
+- Simple API for integration into projects
+- Lightweight and dependency-free design
+
+Installation:
+- pip install clarix
+
+Usage:
+- import clarix
+- clarix.enable()
+
+Current Status:
+- Early development version (0.0.1)
+- Core functionality under expansion
+
+Future Plans:
+- Detailed error categorization
+- Improved explanation engine
+- Support for advanced debugging insights

clarix-0.0.2/clarix/__init__.py

@@ -0,0 +1,187 @@
+# clarix/__init__.py
+
+"""
+CLARIX — Python Error Explanation Engine
+========================================
+
+Overview
+--------
+Clarix is a developer-focused utility designed to analyze Python exceptions
+and present them in a structured, human-readable format. It enhances debugging
+by transforming raw error traces into clear explanations with contextual hints.
+
+The system is particularly useful for beginners, learners, and rapid development
+environments where understanding errors efficiently is critical.
+
+------------------------------------------------------------
+
+Installation
+------------
+Install Clarix via pip:
+
+    pip install clarix
+
+Ensure Python version compatibility before installation.
+
+------------------------------------------------------------
+
+Quick Start
+-----------
+There are two primary ways to use Clarix:
+
+1. Command-Line Interface (CLI)
+
+    clarix-run <file.py>
+
+Example:
+
+    clarix-run test.py
+
+This will execute the script and display formatted error output
+if an exception occurs.
+
+2. Programmatic Usage
+
+    import clarix
+    clarix.run("<folder/file.py>")
+
+You may also pass file paths explicitly.
+
+------------------------------------------------------------
+
+Core Features
+-------------
+• Structured Error Display
+  Errors are presented using formatted tables and panels for clarity.
+
+• Syntax Highlighting
+  Relevant code sections are displayed with visual emphasis.
+
+• Contextual Explanation
+  Provides simplified explanations of Python errors.
+
+• File and Line Tracking
+  Displays exact file name and line number where the error occurred.
+
+• Enhanced Readability
+  Uses styled output (via rich formatting) to improve debugging experience.
+
+------------------------------------------------------------
+
+Supported Error Types
+---------------------
+Clarix currently supports analysis of common Python exceptions, including:
+
+• SyntaxError
+• NameError
+• TypeError
+• ValueError
+• IndexError
+• KeyError
+
+Support for additional error types may be added in future releases.
+
+------------------------------------------------------------
+
+Versioning
+----------
+Clarix follows semantic versioning:
+
+    MAJOR.MINOR.PATCH
+
+• PATCH: Bug fixes
+• MINOR: New features (backward-compatible)
+• MAJOR: Breaking changes
+
+Example:
+
+    0.1.0 → Initial release
+    0.1.1 → Bug fix
+    0.2.0 → Feature addition
+
+------------------------------------------------------------
+
+Updating Clarix
+---------------
+To update to the latest version:
+
+    pip install --upgrade clarix
+
+Ensure your environment has internet access and appropriate permissions.
+
+------------------------------------------------------------
+
+Design Philosophy
+-----------------
+Clarix is built on the principle that debugging should be intuitive.
+Instead of forcing developers to interpret dense tracebacks, the tool
+acts as an interpreter layer—translating machine-level exceptions into
+human-level understanding.
+
+------------------------------------------------------------
+
+Limitations
+-----------
+• Does not replace Python's native traceback system
+• Complex runtime errors may still require manual inspection
+• Dependent on correct environment configuration
+
+------------------------------------------------------------
+
+Best Practices
+--------------
+• Use Clarix during development, not in production pipelines
+• Combine with logging for deeper debugging workflows
+• Regularly update to access improved explanations
+
+------------------------------------------------------------
+
+Future Enhancements (Planned)
+----------------------------
+• Support for more exception types
+• Integration with IDEs
+• Auto-update notifications
+
+------------------------------------------------------------
+
+Author
+------
+Developed as an independent Python utility project.
+
+------------------------------------------------------------
+
+License
+-------
+MIT License
+
+Copyright (c) 2026 Kane Bean
+
+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.
+
+------------------------------------------------------------
+
+End of Manual
+-------------
+"""
+
+from .core import enable, boot
+from .core import enable
+from .runner import run
+
+__all__ = ["enable", "run" , "boot"]

clarix-0.0.2/clarix/cli.py

@@ -0,0 +1,16 @@
+# clarix/cli.py
+
+import sys
+from clarix.runner import run
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: clarix-run <file_or_folder>")
+        sys.exit(1)
+
+    run(sys.argv[1])
+
+
+if __name__ == "__main__":
+    main()

clarix-0.0.2/clarix/context.py

@@ -0,0 +1,22 @@
+import linecache
+import traceback
+
+
+def get_context(tb):
+    tb_list = traceback.extract_tb(tb)
+    last = tb_list[-1] if tb_list else None
+
+    if not last:
+        return {"filename": None, "line": None, "code": None}
+
+    code = (last.line or "").strip()
+
+    if not code and last.filename and last.lineno:
+        linecache.checkcache(last.filename)
+        code = linecache.getline(last.filename, last.lineno).strip()
+
+    return {
+        "filename": last.filename,
+        "line": last.lineno,
+        "code": code,
+    }

clarix-0.0.2/clarix/core.py

@@ -0,0 +1,55 @@
+# clarix/core.py
+
+import sys
+from .engine import process_exception
+from .context import get_context
+from .ui.rich_ui import show_runtime_error
+
+_original_hook = sys.excepthook
+
+
+def _hook(exc_type, exc_value, traceback):
+    try:
+        message = process_exception(exc_type, exc_value, traceback)
+        ctx = get_context(traceback)
+
+        show_runtime_error(
+            message=message,
+            line=ctx.get("line"),
+            code=ctx.get("code"),
+            filename=ctx.get("filename")
+            )
+
+    except Exception:
+        _original_hook(exc_type, exc_value, traceback)
+
+
+def enable():
+    print("\n⚠️ Clarix enabled (runtime mode)")
+    print("💡 Syntax errors require CLI: clarix-run <file>\n")
+
+    sys.excepthook = _hook
+    
+
+def boot():
+    """
+    Executes the current script under Clarix control
+    """
+    import runpy
+
+    try:
+        runpy.run_path(sys.argv[0], run_name="__main__")
+
+    except SyntaxError as e:
+        print(f"""
+[Notice: Future upgrade 🚧]
+
+⚠️ Syntax Error detected
+🧠 Clarix is improving syntax-level understanding.
+
+📍 Line {e.lineno}: {e.text.strip() if e.text else ''}
+🔍 Message: {e.msg}
+""")
+
+    except Exception as e:
+        print(process_exception(type(e), e, e.__traceback__))

clarix-0.0.2/clarix/engine.py

@@ -0,0 +1,20 @@
+# clarix/engine.py
+
+from .handlers import name_error, type_error, zero_division
+from .context import get_context
+
+def process_exception(exc_type, exc_value, tb):
+    context = get_context(tb)
+    name = exc_type.__name__
+
+    if name == "NameError":
+        return name_error.handle(exc_value, context)
+
+    elif name == "TypeError":
+        return type_error.handle(exc_value, context)
+
+    elif name == "ZeroDivisionError":
+        return zero_division.handle(exc_value, context)
+
+    return f"❌ {name}: {exc_value}"
+    

clarix-0.0.2/clarix/handlers/__init__.py

@@ -0,0 +1,11 @@
+# clarix/handlers/__init__.py
+
+from . import name_error
+from . import type_error
+from . import zero_division
+
+__all__ = [
+    "name_error",
+    "type_error",
+    "zero_division",
+]

clarix-0.0.2/clarix/handlers/name_error.py

@@ -0,0 +1,23 @@
+# clarix/handlers/name_error.py
+
+# clarix/handlers/name_error.py
+
+import re
+from ..utils.suggestions import suggest_name
+
+def handle(exc_value, context):
+    msg = str(exc_value)
+
+    match = re.search(r"name '(.+)' is not defined", msg)
+    if not match:
+        return f"❌ NameError: {msg}"
+
+    var = match.group(1)
+    suggestion = suggest_name(var)
+
+    base = f"❌ Variable '{var}' is not defined."
+
+    if suggestion:
+        base += f"\n💡 Did you mean '{suggestion}'?"
+
+    return base

clarix-0.0.2/clarix/handlers/type_error.py

@@ -0,0 +1,16 @@
+# clarix/handlers/type_error.py
+
+def handle(exc_value, context):
+    msg = str(exc_value)
+
+    explanation = "You're trying to use incompatible data types."
+
+    if "unsupported operand" in msg:
+        explanation = "You tried an operation between incompatible types (e.g., string + int)."
+
+    return (
+        f"❌ Type Error\n"
+        f"🧠 {explanation}\n"
+        f"⚠️ {msg}"
+    )
+    

clarix-0.0.2/clarix/handlers/zero_division.py

@@ -0,0 +1,7 @@
+# clarix/handlers/zero_division.py
+
+def handle(exc_value, context):
+    return (
+        "❌ Division by Zero\n"
+        "🧠 You cannot divide a number by zero because it is undefined.\n"
+    )

clarix-0.0.2/clarix/ui/__init__.py

@@ -0,0 +1,3 @@
+from .rich_ui import show_syntax_error, show_runtime_error
+
+__all__ = ["show_syntax_error", "show_runtime_error"]

clarix-0.0.2/clarix/ui/rich_ui.py

@@ -0,0 +1,97 @@
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.box import ROUNDED
+
+console = Console()
+
+
+# 🔴 SYNTAX ERROR DISPLAY
+def show_syntax_error(err, path, code_line):
+    title = Text("⚠️ CLARIX SYNTAX ERROR", style="bold yellow")
+
+    # 📂 File Info Table (with zebra striping)
+    table = Table(
+        box=ROUNDED,
+        expand=True,
+        row_styles=["cyan", "purple"]  # ← zebra stripes
+    )
+    table.add_column("Field", style="bold cyan")
+    table.add_column("Value", style="white")
+
+    table.add_row("File", str(path))
+    table.add_row("Line", str(err.lineno))
+    table.add_row("Error", err.msg)
+
+    # 💻 Highlighted Code
+    syntax = Syntax(
+        code_line,
+        "python",
+        theme="monokai",
+        line_numbers=False
+    )
+
+    # 🧠 Insight Text
+    insight = Text(
+        "\nThis error occurs before execution (parsing stage).\n"
+        "Likely causes: typo, missing operator, or invalid syntax.",
+        style="italic dim"
+    )
+
+    panel = Panel(
+        table,
+        title=title,
+        border_style="yellow",
+        padding=(1, 2)
+    )
+
+    console.print(panel)
+    console.print("\n💻 Buggy Line:\n", syntax)
+    console.print(insight)
+
+
+# 🔴 RUNTIME ERROR DISPLAY
+def show_runtime_error(message, line=None, code=None, filename=None):
+    title = Text("❌ CLARIX RUNTIME ERROR", style="bold red")
+
+    # 📂 Info Table (with zebra striping)
+    table = Table(
+        box=ROUNDED,
+        expand=True,
+        row_styles=["cyan", "purple"]  # ← zebra stripes
+    )
+    table.add_column("Field", style="bold magenta")
+    table.add_column("Value", style="white")
+
+    if filename:
+        table.add_row("File", str(filename))
+    if line:
+        table.add_row("Line", str(line))
+
+    # 💻 Code Highlight
+    syntax_block = None
+    if code:
+        syntax_block = Syntax(
+            code,
+            "python",
+            theme="monokai",
+            line_numbers=False
+        )
+
+    # 🧠 Main Message
+    message_text = Text(message, style="bold")
+
+    panel = Panel(
+        table,
+        title=title,
+        border_style="red",
+        padding=(1, 2)
+    )
+
+    console.print(panel)
+    console.print("\n🧠 Explanation:\n", message_text)
+
+    if syntax_block:
+        console.print("\n💻 Buggy Line:\n", syntax_block)

clarix-0.0.2/clarix/utils/__init__.py

@@ -0,0 +1,5 @@
+# clarix/utils/__init__.py
+
+from .suggestions import suggest_name
+
+__all__ = ["suggest_name"]

clarix-0.0.2/clarix/utils/parser.py

@@ -0,0 +1,20 @@
+# clarix/utils/parser.py
+
+import re
+
+def extract_name_error(msg):
+    match = re.search(r"name '(.+)' is not defined", msg)
+    return match.group(1) if match else None
+
+
+def extract_type_error_operands(msg):
+    match = re.search(r"unsupported operand type\(s\) for (.+): '(.+)' and '(.+)'", msg)
+    
+    if match:
+        return {
+            "operator": match.group(1),
+            "left": match.group(2),
+            "right": match.group(3),
+        }
+    
+    return None

clarix-0.0.2/clarix/utils/suggestions.py

@@ -0,0 +1,10 @@
+# clarix/utils/suggestions.py
+
+import difflib
+import builtins
+
+def suggest_name(name):
+    pool = dir(builtins)
+
+    matches = difflib.get_close_matches(name, pool, n=1)
+    return matches[0] if matches else None

clarix-0.0.2/clarix.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: clarix
+Version: 0.0.2
+Summary: A smart Python error explainer with rich UI and structured insights
+Author: Kane
+License: MIT
+Keywords: python,debugging,error-explainer,rich,cli,developer-tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+clarix
+------
+
+clarix is a lightweight Python module for explaining and analyzing runtime errors.
+
+Features:
+- Basic error explanation interface
+- Simple API for integration into projects
+- Lightweight and dependency-free design
+
+Installation:
+- pip install clarix
+
+Usage:
+- import clarix
+- clarix.enable()
+
+Current Status:
+- Early development version (0.0.1)
+- Core functionality under expansion
+
+Future Plans:
+- Detailed error categorization
+- Improved explanation engine
+- Support for advanced debugging insights

clarix-0.0.2/clarix.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+clarix/__init__.py
+clarix/cli.py
+clarix/context.py
+clarix/core.py
+clarix/engine.py
+clarix.egg-info/PKG-INFO
+clarix.egg-info/SOURCES.txt
+clarix.egg-info/dependency_links.txt
+clarix.egg-info/entry_points.txt
+clarix.egg-info/requires.txt
+clarix.egg-info/top_level.txt
+clarix/handlers/__init__.py
+clarix/handlers/name_error.py
+clarix/handlers/type_error.py
+clarix/handlers/zero_division.py
+clarix/ui/__init__.py
+clarix/ui/rich_ui.py
+clarix/utils/__init__.py
+clarix/utils/parser.py
+clarix/utils/suggestions.py

clarix-0.0.2/clarix.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clarix-0.0.2/clarix.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clarix-run = clarix.cli:main

clarix-0.0.2/clarix.egg-info/requires.txt

@@ -0,0 +1,6 @@
+rich>=13.0.0
+
+[dev]
+pytest
+black
+flake8

clarix-0.0.2/clarix.egg-info/top_level.txt

@@ -0,0 +1 @@
+clarix

clarix-0.0.2/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "clarix"
+version = "0.0.2"
+description = "A smart Python error explainer with rich UI and structured insights"
+readme = "README.md"
+authors = [
+    { name = "Kane" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+
+keywords = ["python", "debugging", "error-explainer", "rich", "cli", "developer-tools"]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Debuggers",
+]
+
+
+dependencies = [
+    "rich>=13.0.0"
+]
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "black",
+    "flake8"
+]
+
+
+[project.scripts]
+clarix-run = "clarix.cli:main"
+
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["clarix*"]
+
+
+[tool.setuptools.package-data]
+clarix = ["*.txt", "*.md"]

clarix-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+