butwhy 0.1.0__py3-none-any.whl

butwhy/__init__.py

@@ -0,0 +1,337 @@
+"""
+why — Stop guessing. Start understanding.
+
+    import butwhy
+
+That's it. Your Python errors now explain themselves.
+
+Three ways to use:
+
+    1. Global (recommended):
+        import butwhy
+        1 / 0  # boom — why explains it
+
+    2. Context manager:
+        with butwhy.trace():
+            1 / 0
+
+    3. Decorator:
+        @butwhy.explain
+        def divide(a, b):
+            return a / b
+
+Set OPENAI_API_KEY or ANTHROPIC_API_KEY for AI-powered explanations.
+No key? why falls back to built-in pattern matching. Still useful.
+
+    >>> import butwhy
+    >>> butwhy.this
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+__version__ = "0.1.0"
+__author__ = "why contributors"
+__license__ = "MIT"
+
+# ── Re-export public API ──────────────────────────────────────────
+
+from .config import get_config, set_config, WhyConfig
+from .explainer import explain_error
+from .hook import install, uninstall, is_active, trace, explain
+from .cache import clear_cache
+
+# ── Auto-install ──────────────────────────────────────────────────
+
+if os.environ.get("BUTWHY_AUTOSTART", "1") != "0":
+    install()
+
+
+# ── butwhy.this — The Zen of Why ────────────────────────────────────
+
+_ZEN_OF_WHY = """\
+The Zen of Why, by why
+
+Errors are not failures, they are teachers.
+The traceback tells you what; why tells you why.
+A good message answers the question before you ask it.
+Read the variables, not just the line numbers.
+If the error is obvious, the fix should be too.
+Names matter: 'NoneType has no attribute' should mean something.
+Context is king: a line number without variables is half a story.
+The best debug is the one you didn't have to Google.
+Simple errors deserve simple words.
+Automate the explanation, not the understanding.
+Now is better than never.
+Although never is often better than *right* now.
+If the implementation is hard to explain, it's a bad implementation.
+If the implementation is easy to explain, it may be good.
+Errors should never pass silently.
+Unless explicitly silenced.
+In the face of ambiguity, refuse the temptation to guess.
+There should be one-- and preferably only one --obvious way to fix it.
+Although that way may not be obvious at first unless you're why.
+If why is not enough, read the source, Luke."""
+
+
+class _This:
+    """Printing this shows the Zen of Why. Like `import this`."""
+
+    def __repr__(self) -> str:
+        return _ZEN_OF_WHY
+
+    def __str__(self) -> str:
+        return _ZEN_OF_WHY
+
+    def _print(self):
+        print(_ZEN_OF_WHY)
+
+
+this = _This()
+
+
+# ── butwhy.fix() — Interactive auto-fix ─────────────────────────────
+
+def fix(filepath: str | None = None, *, auto: bool = False) -> bool:
+    """Attempt to auto-fix the most recent error's source file.
+
+    After an error occurs, call butwhy.fix() to:
+      1. Get an AI-generated code patch for the failing line
+      2. Preview the diff
+      3. Apply the fix (with confirmation unless auto=True)
+
+    Args:
+        filepath: Path to the file to fix. If None, uses the last
+                  error's file.
+        auto: If True, skip confirmation prompt.
+
+    Returns True if a fix was applied, False otherwise.
+
+    Note: Requires an AI provider (set OPENAI_API_KEY or similar).
+          Pattern-matching mode cannot generate code patches.
+    """
+    from .explainer import _get_provider
+    from .config import get_config
+
+    cfg = get_config()
+    provider = _get_provider()
+
+    if not provider or not provider.is_available():
+        print(
+            "butwhy.fix() requires an AI provider.\n"
+            "Set OPENAI_API_KEY or ANTHROPIC_API_KEY to use this feature.",
+            file=sys.stderr,
+        )
+        return False
+
+    # We need the last error context — stored by the excepthook
+    last_error = getattr(sys, "_butwhy_last_error", None)
+    if last_error is None:
+        print(
+            "No recent error to fix. Run some code that crashes first.",
+            file=sys.stderr,
+        )
+        return False
+
+    exc = last_error["exc"]
+    frame_info = last_error["frame_info"]
+
+    target_file = filepath or frame_info.get("file", "")
+    lineno = frame_info.get("lineno", 0)
+    source_line = frame_info.get("source_line", "")
+
+    if not target_file or not os.path.exists(target_file):
+        print(f"Cannot find file to fix: {target_file}", file=sys.stderr)
+        return False
+
+    # Read the file
+    with open(target_file, "r", encoding="utf-8") as f:
+        file_lines = f.readlines()
+
+    # Build fix prompt
+    context_str = "\n".join(frame_info.get("source_context", []))
+
+    if cfg.language == "zh":
+        prompt = f"""请修复以下 Python 代码中的错误。
+
+文件: {target_file}
+错误行 ({lineno}): {source_line}
+错误: {type(exc).__name__}: {exc}
+
+代码上下文:
+{context_str}
+
+请只返回修复后的那一行代码（不要返回整个文件，不要加markdown标记）。
+如果需要多行修复，返回替换代码块，用 --- 分隔旧行和新行。"""
+    else:
+        prompt = f"""Fix the error in this Python code.
+
+File: {target_file}
+Failing line ({lineno}): {source_line}
+Error: {type(exc).__name__}: {exc}
+
+Code context:
+{context_str}
+
+Return ONLY the fixed line(s) of code. No markdown fences, no explanation.
+If multiple lines need changing, return them as a code block."""
+
+    try:
+        fix_code = provider.explain(prompt, timeout=cfg.timeout)
+    except Exception as e:
+        print(f"Failed to generate fix: {e}", file=sys.stderr)
+        return False
+
+    # Clean up the response
+    fix_code = fix_code.strip()
+    if fix_code.startswith("```"):
+        lines = fix_code.split("\n")
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        fix_code = "\n".join(lines).strip()
+
+    # Show diff
+    print(f"\n  Suggested fix for {target_file}:{lineno}\n", file=sys.stderr)
+    print(f"  {'-' * 50}", file=sys.stderr)
+    print(f"  - {source_line}", file=sys.stderr)
+    print(f"  + {fix_code}", file=sys.stderr)
+    print(f"  {'-' * 50}\n", file=sys.stderr)
+
+    # Confirm
+    if not auto:
+        try:
+            response = input("  Apply this fix? [y/N] ").strip().lower()
+            if response not in ("y", "yes"):
+                print("  Fix not applied.", file=sys.stderr)
+                return False
+        except (EOFError, KeyboardInterrupt):
+            print("\n  Fix not applied.", file=sys.stderr)
+            return False
+
+    # Apply fix — replace the line
+    if 0 < lineno <= len(file_lines):
+        new_lines = fix_code.split("\n")
+        file_lines[lineno - 1: lineno] = [l + "\n" for l in new_lines]
+
+        with open(target_file, "w", encoding="utf-8") as f:
+            f.writelines(file_lines)
+
+        print(f"  Applied fix to {target_file}:{lineno}", file=sys.stderr)
+        return True
+
+    return False
+
+
+# ── butwhy.report() — Error statistics ──────────────────────────────
+
+_error_stats: list[dict] = []
+
+
+def _record_error(exc: BaseException, frame_info: dict):
+    """Record an error for statistics (called by the hook)."""
+    _error_stats.append({
+        "type": type(exc).__name__,
+        "message": str(exc),
+        "file": frame_info.get("file", ""),
+        "func": frame_info.get("func", ""),
+    })
+
+
+def report(top: int = 5) -> str:
+    """Show a summary of errors encountered in this session.
+
+    Args:
+        top: Number of most common error types to show.
+
+    Returns a formatted string showing error frequency.
+    """
+    if not _error_stats:
+        return "No errors recorded in this session."
+
+    from collections import Counter
+
+    type_counts = Counter(e["type"] for e in _error_stats)
+    msg_counts = Counter(
+        f"{e['type']}: {e['message'][:60]}" for e in _error_stats
+    )
+
+    lines = [f"\n  butwhy.report() — {len(_error_stats)} error(s) this session\n"]
+
+    lines.append(f"  Top {top} error types:")
+    for etype, count in type_counts.most_common(top):
+        bar = "#" * count
+        lines.append(f"    {etype:25s} {count:3d} {bar}")
+
+    lines.append(f"\n  Top {top} recurring errors:")
+    for msg, count in msg_counts.most_common(top):
+        lines.append(f"    [{count}x] {msg}")
+
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+# ── Jupyter / IPython magic ───────────────────────────────────────
+
+def _load_ipython_extension(ipython):
+    """Register %why magic for Jupyter/IPython.
+
+    Usage in a notebook:
+        %load_ext why
+        # or
+        import butwhy  # auto-registers
+
+    Then all cell errors are explained automatically.
+    """
+    from IPython.core.magic import Magics, magics_class, line_magic
+
+    @magics_class
+    class WhyMagics(Magics):
+        @line_magic
+        def why(self, line):
+            """Toggle why error explanations in this notebook."""
+            if line.strip() == "off":
+                uninstall()
+                print("why: explanations disabled")
+            elif line.strip() == "report":
+                print(report())
+            else:
+                install()
+                print("why: explanations enabled — errors will be explained")
+
+    ipython.register_magics(WhyMagics)
+
+    # Also install the global hook
+    install()
+
+
+# Auto-register with IPython if available
+try:
+    from IPython import get_ipython
+    ip = get_ipython()
+    if ip is not None:
+        _load_ipython_extension(ip)
+except ImportError:
+    pass
+
+
+# ── __all__ ───────────────────────────────────────────────────────
+
+__all__ = [
+    "install",
+    "uninstall",
+    "is_active",
+    "trace",
+    "explain",
+    "explain_error",
+    "this",
+    "fix",
+    "report",
+    "get_config",
+    "set_config",
+    "WhyConfig",
+    "clear_cache",
+    "cli",
+    "__version__",
+]

butwhy/__main__.py

@@ -0,0 +1,27 @@
+"""
+Support `python -m butwhy` — prints version and Zen of Why.
+
+    python -m butwhy          # prints version + this
+    python -m butwhy --version
+"""
+
+import sys
+
+
+def main():
+    from . import __version__, this
+
+    if "--version" in sys.argv or "-V" in sys.argv:
+        print(f"butwhy {__version__}")
+        return
+
+    print(f"butwhy {__version__}")
+    print()
+    print(this)
+    print()
+    print("Usage: import butwhy  —  your errors will be explained.")
+    print("       set OPENAI_API_KEY=sk-... for AI-powered explanations.")
+
+
+if __name__ == "__main__":
+    main()

butwhy/cache.py

@@ -0,0 +1,105 @@
+"""
+On-disk caching for AI explanations.
+
+Caches by a hash of (exception_type + message + source_line + local_vars).
+This avoids redundant API calls when the same error keeps firing
+(e.g. in a loop or across repeated runs).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from typing import Optional
+
+
+def _cache_key(exc_type: str, message: str, source_line: str, local_vars: dict) -> str:
+    """Generate a stable cache key from the error signature."""
+    # Include a compact representation of local var types+values
+    var_sig = json.dumps(
+        {k: {"t": v["type"], "v": v["value"][:50]} for k, v in local_vars.items()},
+        sort_keys=True,
+    )
+    raw = f"{exc_type}|{message}|{source_line}|{var_sig}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def _cache_path(cache_dir: str, key: str) -> str:
+    return os.path.join(cache_dir, f"why_{key}.json")
+
+
+def get_cached(
+    exc_type: str,
+    message: str,
+    source_line: str,
+    local_vars: dict,
+    cache_dir: str,
+    ttl: int = 86400 * 7,  # 7 days
+) -> Optional[str]:
+    """Retrieve a cached explanation if it exists and hasn't expired."""
+    if not cache_dir:
+        return None
+
+    key = _cache_key(exc_type, message, source_line, local_vars)
+    path = _cache_path(cache_dir, key)
+
+    if not os.path.exists(path):
+        return None
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if time.time() - data.get("ts", 0) > ttl:
+            return None
+        return data.get("explanation")
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def set_cached(
+    exc_type: str,
+    message: str,
+    source_line: str,
+    local_vars: dict,
+    explanation: str,
+    cache_dir: str,
+) -> None:
+    """Store an explanation in the cache."""
+    if not cache_dir:
+        return
+
+    try:
+        os.makedirs(cache_dir, exist_ok=True)
+    except OSError:
+        return
+
+    key = _cache_key(exc_type, message, source_line, local_vars)
+    path = _cache_path(cache_dir, key)
+
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(
+                {"ts": time.time(), "explanation": explanation, "key": key},
+                f,
+                ensure_ascii=False,
+            )
+    except OSError:
+        pass
+
+
+def clear_cache(cache_dir: str) -> int:
+    """Clear all cached explanations. Returns the number of files removed."""
+    if not cache_dir or not os.path.isdir(cache_dir):
+        return 0
+
+    count = 0
+    for fname in os.listdir(cache_dir):
+        if fname.startswith("why_") and fname.endswith(".json"):
+            try:
+                os.remove(os.path.join(cache_dir, fname))
+                count += 1
+            except OSError:
+                pass
+    return count

butwhy/cli.py

@@ -0,0 +1,88 @@
+"""
+CLI entry point — `butwhy` command line tool.
+
+    butwhy                    # show version + Zen of Why
+    butwhy --version          # version only
+    butwhy --explain file.py  # run a script and explain any errors
+    butwhy --clear-cache      # clear explanation cache
+"""
+
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="butwhy",
+        description="Stop guessing. Start understanding. Your Python errors, explained.",
+    )
+    parser.add_argument(
+        "-V", "--version",
+        action="store_true",
+        help="Print version and exit",
+    )
+    parser.add_argument(
+        "--explain",
+        metavar="FILE",
+        help="Run a Python file and explain any errors that occur",
+    )
+    parser.add_argument(
+        "--clear-cache",
+        action="store_true",
+        help="Clear the explanation cache",
+    )
+    parser.add_argument(
+        "--language",
+        choices=["en", "zh"],
+        default=None,
+        help="Set explanation language (en or zh)",
+    )
+
+    args = parser.parse_args()
+
+    if args.version:
+        from butwhy import __version__
+        print(f"butwhy {__version__}")
+        return 0
+
+    if args.clear_cache:
+        from butwhy.cache import clear_cache
+        import tempfile
+        import os
+        cache_dir = os.path.join(tempfile.gettempdir(), "butwhy_cache")
+        count = clear_cache(cache_dir)
+        print(f"Cleared {count} cached explanation(s).")
+        return 0
+
+    if args.language:
+        import os
+        os.environ["BUTWHY_LANGUAGE"] = args.language
+
+    if args.explain:
+        script = args.explain
+        code = f"import butwhy; exec(open('{script}', encoding='utf-8').read())"
+        try:
+            exec(compile(code, script, "exec"), {"__name__": "__main__"})
+        except SystemExit:
+            pass
+        except BaseException:
+            pass
+        return 0
+
+    # Default: show version + Zen
+    from butwhy import __version__, this
+    print(f"butwhy {__version__}")
+    print()
+    print(this)
+    print()
+    print("Usage:")
+    print("  import butwhy              # enable error explanations")
+    print("  butwhy --explain file.py   # run a file with explanations")
+    print("  butwhy --clear-cache       # clear cached explanations")
+    print()
+    print("Set OPENAI_API_KEY for AI-powered deep explanations.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

butwhy/config.py

@@ -0,0 +1,134 @@
+"""
+Configuration and provider auto-detection for why.
+
+Why has zero required configuration. It auto-detects available
+LLM providers from environment variables and falls back to
+built-in pattern matching when no provider is available.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class WhyConfig:
+    """Runtime configuration for why.
+
+    All fields have sensible defaults. Users can override via
+    environment variables or by constructing a custom config
+    and passing it to ``why.init()``.
+    """
+
+    # Provider settings
+    provider: str = "auto"  # auto | openai | anthropic | ollama | patterns
+
+    # OpenAI
+    openai_api_key: Optional[str] = None
+    openai_model: str = "gpt-4o-mini"
+    openai_base_url: str = "https://api.openai.com/v1"
+
+    # Anthropic
+    anthropic_api_key: Optional[str] = None
+    anthropic_model: str = "claude-3-5-sonnet-20241022"
+    anthropic_base_url: str = "https://api.anthropic.com"
+
+    # Ollama (local)
+    ollama_url: str = "http://localhost:11434"
+    ollama_model: str = "qwen2.5-coder:7b"
+
+    # Behavior
+    language: str = "en"  # en | zh
+    cache: bool = True
+    cache_dir: str = ""
+    show_source: bool = True
+    show_vars: bool = True
+    show_fix: bool = True
+    context_lines: int = 5
+    max_var_len: int = 200
+    timeout: int = 30
+
+    # Internal
+    _active_provider: str = field(default="", init=False, repr=False)
+
+    @classmethod
+    def from_env(cls) -> "WhyConfig":
+        """Build config from environment variables."""
+        cfg = cls()
+
+        cfg.openai_api_key = os.environ.get("OPENAI_API_KEY")
+        cfg.anthropic_api_key = os.environ.get("ANTHROPIC_API_KEY")
+
+        if v := os.environ.get("BUTWHY_PROVIDER"):
+            cfg.provider = v
+        if v := os.environ.get("BUTWHY_LANGUAGE"):
+            cfg.language = v
+        if v := os.environ.get("BUTWHY_MODEL"):
+            # Set model for whichever provider is active
+            if cfg.provider == "openai":
+                cfg.openai_model = v
+            elif cfg.provider == "anthropic":
+                cfg.anthropic_model = v
+            elif cfg.provider == "ollama":
+                cfg.ollama_model = v
+        if v := os.environ.get("BUTWHY_CACHE_DIR"):
+            cfg.cache_dir = v
+        if v := os.environ.get("OPENAI_BASE_URL"):
+            cfg.openai_base_url = v
+        if v := os.environ.get("OLLAMA_URL"):
+            cfg.ollama_url = v
+        if v := os.environ.get("OLLAMA_MODEL"):
+            cfg.ollama_model = v
+
+        if v := os.environ.get("BUTWHY_TIMEOUT"):
+            try:
+                cfg.timeout = int(v)
+            except ValueError:
+                pass
+
+        return cfg
+
+    def resolve_provider(self) -> str:
+        """Determine which provider to actually use.
+
+        Resolution order when provider == 'auto':
+            1. OpenAI  (if OPENAI_API_KEY is set)
+            2. Anthropic (if ANTHROPIC_API_KEY is set)
+            3. Ollama  (if local server is reachable — checked lazily)
+            4. patterns (built-in, always available)
+        """
+        if self.provider != "auto":
+            self._active_provider = self.provider
+            return self.provider
+
+        if self.openai_api_key:
+            self._active_provider = "openai"
+        elif self.anthropic_api_key:
+            self._active_provider = "anthropic"
+        else:
+            # Ollama is checked lazily at call time; default to patterns
+            # so we never block on a network request during import.
+            self._active_provider = "patterns"
+
+        return self._active_provider
+
+
+# ── Global singleton ──────────────────────────────────────────────
+
+_config: Optional[WhyConfig] = None
+
+
+def get_config() -> WhyConfig:
+    """Return the active global config, creating it from env if needed."""
+    global _config
+    if _config is None:
+        _config = WhyConfig.from_env()
+    return _config
+
+
+def set_config(cfg: WhyConfig) -> None:
+    """Override the global config."""
+    global _config
+    _config = cfg