clarix 0.1.0__tar.gz

clarix-0.1.0/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.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: clarix
+Version: 0.1.0
+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.1.0/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.1.0/clarix/__init__.py

@@ -0,0 +1,5 @@
+# clarix/__init__.py
+
+from .core import enable, boot
+
+__all__ = ["enable", "boot"]

clarix-0.1.0/clarix/cli.py

@@ -0,0 +1,88 @@
+# clarix/cli.py
+
+import sys
+import ast
+import linecache
+from pathlib import Path
+
+from clarix.engine import process_exception
+from clarix.ui.rich_ui import show_syntax_error, show_runtime_error
+
+
+def _syntax_check(source: str, filename: str):
+    try:
+        ast.parse(source, filename=filename)
+        return None
+    except SyntaxError as err:
+        return err
+
+
+def _get_code_line(path: Path, lineno: int):
+    linecache.checkcache(str(path))
+    return linecache.getline(str(path), lineno).rstrip()
+
+
+def run_file(path_str: str):
+    path = Path(path_str).expanduser().resolve()
+
+    if not path.exists():
+        print(f"❌ File not found: {path}")
+        return
+
+    source = path.read_text(encoding="utf-8")
+
+    # 🔴 Phase 1: Syntax check
+    err = _syntax_check(source, filename=str(path))
+
+    if err:
+        code_line = ""
+
+        if err.lineno:
+            code_line = _get_code_line(path, err.lineno)
+
+        if not code_line and err.text:
+            code_line = err.text.rstrip()
+
+        show_syntax_error(err, path, code_line)
+        return
+
+    # 🟢 Phase 2: Execution
+    try:
+        code_obj = compile(source, str(path), "exec")
+
+        globals_dict = {
+            "__name__": "__main__",
+            "__file__": str(path),
+            "__package__": None,
+        }
+
+        exec(code_obj, globals_dict, globals_dict)
+
+    except Exception as exc:
+        tb = exc.__traceback__
+
+        # Use engine
+        message = process_exception(type(exc), exc, tb)
+
+        # Extract context again for display
+        from clarix.context import get_context
+        ctx = get_context(tb)
+
+        show_runtime_error(
+            message=message,
+            line=ctx.get("line"),
+            code=ctx.get("code"),
+            filename=ctx.get("filename")
+            )
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: clarix-run <file.py>")
+        sys.exit(1)
+
+    run_file(sys.argv[1])
+
+
+if __name__ == "__main__":
+    main()

clarix-0.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/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.1.0/clarix/utils/__init__.py

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

clarix-0.1.0/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.1.0/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.1.0/clarix.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: clarix
+Version: 0.1.0
+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.1.0/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.1.0/clarix.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

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

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

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

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

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

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

clarix-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "clarix"
+version = "0.1.0"
+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.1.0/setup.cfg

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