failwith 0.1.0__tar.gz

failwith-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `failwith` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-29
+
+### Added
+
+- Core `failwith.install()` one-liner activation
+- `failwith.catch()` context manager and decorator
+- `@failwith.register()` custom suggestion handler API
+- 20 built-in error type handlers:
+  - `ModuleNotFoundError` with 120+ import→package name mappings
+  - `ImportError` with fuzzy name matching and circular import detection
+  - `ConnectionRefusedError` with port-aware service suggestions
+  - `TimeoutError` and `ConnectionResetError` with network debug tips
+  - `FileNotFoundError` with similar file search and directory listing
+  - `PermissionError` with ownership and chmod/chown suggestions
+  - `KeyError` with fuzzy matching against available keys
+  - `AttributeError` with fuzzy matching and NoneType detection
+  - `NameError` with scope-aware fuzzy matching
+  - `TypeError` with common pattern fixes (str+int, not callable, etc.)
+  - `ValueError` with conversion and unpacking suggestions
+  - `IndexError` with collection size context
+  - `ZeroDivisionError` with zero-valued variable identification
+  - `UnicodeDecodeError` / `UnicodeEncodeError` with encoding suggestions
+  - `RecursionError` with recursion limit and call chain info
+  - `MemoryError` with optimization strategies
+  - `SyntaxError` with common fix patterns
+  - `json.JSONDecodeError` with error position context
+  - `StopIteration` with next() default suggestion
+  - `OSError` with errno-specific suggestions (disk full, too many files, port in use)
+- Port→service mapping database (40+ common ports)
+- Environment diagnostics (Python version, venv, OS detection)
+- ANSI color output with graceful plain-text fallback
+- Cross-platform support (Linux, macOS, Windows)
+- Zero runtime dependencies

failwith-0.1.0/LICENSE

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

failwith-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include src *.py
+recursive-include tests *.py

failwith-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: failwith
+Version: 0.1.0
+Summary: Actionable error intelligence for Python — tells you why errors happen and how to fix them.
+Author-email: Yashraj Aware <yashrajaware2003@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Yashraj-Aware/failwith.git
+Project-URL: Repository, https://github.com/Yashraj-Aware/failwith
+Project-URL: Issues, https://github.com/Yashraj-Aware/failwith/issues
+Keywords: errors,traceback,debugging,developer-tools,exceptions,diagnostics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: rich
+Requires-Dist: rich>=12.0.0; extra == "rich"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# failwith 
+
+**Actionable error intelligence for Python.**
+
+When Python tells you *what* broke, `failwith` tells you *why* and *how to fix it*.
+
+```
+pip install failwith
+```
+
+## Quick Start
+
+```python
+import failwith
+failwith.install()
+```
+
+That's it. Every unhandled exception now gets actionable fix suggestions appended below the standard traceback.
+
+## What It Looks Like
+
+```
+Traceback (most recent call last):
+  File "app.py", line 3, in <module>
+    import cv2
+ModuleNotFoundError: No module named 'cv2'
+
+┌─ 💡 failwith ─────────────────────────────────────────────────┐
+│                                                                │
+│  'cv2' is from the 'opencv-python' package (import ≠ package)  │
+│                                                                │
+│  → Install it:    pip install opencv-python                    │
+│  → Or headless:   pip install opencv-python-headless           │
+│  → Active venv:   .venv                                        │
+│                                                                │
+│  🔍 Python 3.11.5 | venv: .venv | Ubuntu 24.04               │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Features
+
+### 1. 200+ Import Name → Package Name Mappings
+
+`cv2` → `opencv-python`, `PIL` → `Pillow`, `sklearn` → `scikit-learn`, `yaml` → `PyYAML`, and 200+ more. Never Google "pip install what?" again.
+
+###  Context-Aware Suggestions
+
+Not pattern matching — actual context analysis. When a `ConnectionRefusedError` hits on port 5432, failwith knows that's PostgreSQL and suggests the right start command for your OS.
+
+### 2. Fuzzy Matching for Typos
+
+`KeyError`, `AttributeError`, and `NameError` get fuzzy-matched against available keys, attributes, and names. "Did you mean 'username'?" with edit distance.
+
+### 3. File System Intelligence
+
+`FileNotFoundError` shows similar files in the directory, current working directory, and the closest existing parent path. `PermissionError` shows file ownership and suggests `chmod`/`chown` commands.
+
+### 4. Environment Diagnostics
+
+Every suggestion includes Python version, venv status, and OS — the three things you always need when debugging.
+
+### 5. Zero Dependencies
+
+Uses only the Python standard library. No `rich`, no `click`, nothing. Zero friction to adopt.
+
+### 6. Never Makes Things Worse
+
+If failwith itself encounters an error, it silently degrades. Your original traceback is always printed first, unmodified.
+
+## Supported Error Types (v0.1)
+
+| Error | What failwith adds |
+|-------|-------------------|
+| `ModuleNotFoundError` | Correct `pip install` command, import↔package mapping |
+| `ImportError` | Fuzzy name matching, circular import detection |
+| `ConnectionRefusedError` | Service name, start commands, Docker suggestions |
+| `TimeoutError` | Network debugging commands |
+| `ConnectionResetError` | Server-side investigation suggestions |
+| `FileNotFoundError` | Similar files, directory listing, working dir |
+| `PermissionError` | File owner, chmod/chown commands |
+| `KeyError` | Fuzzy match against available keys, `.get()` suggestion |
+| `AttributeError` | Fuzzy match against attributes, NoneType detection |
+| `NameError` | Scope-aware fuzzy matching, import suggestions |
+| `TypeError` | Type mismatch fixes (str+int, not callable, etc.) |
+| `ValueError` | Conversion fixes, unpacking mismatch |
+| `IndexError` | Collection size context, safe access |
+| `ZeroDivisionError` | Zero-valued variable identification |
+| `UnicodeDecodeError` | Encoding suggestions, chardet recommendation |
+| `UnicodeEncodeError` | Encoding alternatives, error handling modes |
+| `RecursionError` | Recursion limit, call chain, base case reminder |
+| `MemoryError` | Memory optimization strategies |
+| `SyntaxError` | Common fix patterns (missing colon, Python 2→3) |
+| `JSONDecodeError` | Error position context, common JSON issues |
+| `StopIteration` | `next()` with default, iterator re-creation |
+| `OSError` | Disk space, file descriptor limits, port conflicts |
+
+## Advanced Usage
+
+### Context Manager
+
+```python
+with failwith.catch(reraise=False):
+    risky_operation()
+```
+
+### Decorator
+
+```python
+@failwith.catch()
+def my_function():
+    risky_operation()
+```
+
+### Custom Suggestions
+
+```python
+@failwith.register(MyDatabaseError)
+def handle_db_error(exc_type, exc_value, exc_tb, config):
+    return failwith.Suggestion(
+        title="Database connection failed",
+        fixes=[
+            "Check DATABASE_URL in your .env file",
+            "Run: docker-compose up -d postgres",
+        ],
+    )
+```
+
+### Configuration
+
+```python
+failwith.install(
+    theme="dark",           # "dark" | "light" | "minimal" | "plain"
+    show_locals=False,      # show local variable values
+    max_suggestions=3,      # limit suggestions shown
+)
+```
+
+## Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `NO_COLOR` | Disable colors (standard) |
+| `FAILWITH_NO_COLOR` | Disable colors |
+| `FAILWITH_FORCE_COLOR` | Force colors even in non-TTY |
+
+## Contributing
+
+Contributions are welcome! The most impactful way to contribute:
+
+1. **Add import mappings** — edit `src/failwith/data/import_map.py`
+2. **Improve suggestions** — edit handlers in `src/failwith/suggestions/`
+3. **Add test cases** — real-world error scenarios in `tests/`
+
+```bash
+git clone https://github.com/yashraj/failwith.git
+cd failwith
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

failwith-0.1.0/README.md

@@ -0,0 +1,164 @@
+# failwith 
+
+**Actionable error intelligence for Python.**
+
+When Python tells you *what* broke, `failwith` tells you *why* and *how to fix it*.
+
+```
+pip install failwith
+```
+
+## Quick Start
+
+```python
+import failwith
+failwith.install()
+```
+
+That's it. Every unhandled exception now gets actionable fix suggestions appended below the standard traceback.
+
+## What It Looks Like
+
+```
+Traceback (most recent call last):
+  File "app.py", line 3, in <module>
+    import cv2
+ModuleNotFoundError: No module named 'cv2'
+
+┌─ 💡 failwith ─────────────────────────────────────────────────┐
+│                                                                │
+│  'cv2' is from the 'opencv-python' package (import ≠ package)  │
+│                                                                │
+│  → Install it:    pip install opencv-python                    │
+│  → Or headless:   pip install opencv-python-headless           │
+│  → Active venv:   .venv                                        │
+│                                                                │
+│  🔍 Python 3.11.5 | venv: .venv | Ubuntu 24.04               │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Features
+
+### 1. 200+ Import Name → Package Name Mappings
+
+`cv2` → `opencv-python`, `PIL` → `Pillow`, `sklearn` → `scikit-learn`, `yaml` → `PyYAML`, and 200+ more. Never Google "pip install what?" again.
+
+###  Context-Aware Suggestions
+
+Not pattern matching — actual context analysis. When a `ConnectionRefusedError` hits on port 5432, failwith knows that's PostgreSQL and suggests the right start command for your OS.
+
+### 2. Fuzzy Matching for Typos
+
+`KeyError`, `AttributeError`, and `NameError` get fuzzy-matched against available keys, attributes, and names. "Did you mean 'username'?" with edit distance.
+
+### 3. File System Intelligence
+
+`FileNotFoundError` shows similar files in the directory, current working directory, and the closest existing parent path. `PermissionError` shows file ownership and suggests `chmod`/`chown` commands.
+
+### 4. Environment Diagnostics
+
+Every suggestion includes Python version, venv status, and OS — the three things you always need when debugging.
+
+### 5. Zero Dependencies
+
+Uses only the Python standard library. No `rich`, no `click`, nothing. Zero friction to adopt.
+
+### 6. Never Makes Things Worse
+
+If failwith itself encounters an error, it silently degrades. Your original traceback is always printed first, unmodified.
+
+## Supported Error Types (v0.1)
+
+| Error | What failwith adds |
+|-------|-------------------|
+| `ModuleNotFoundError` | Correct `pip install` command, import↔package mapping |
+| `ImportError` | Fuzzy name matching, circular import detection |
+| `ConnectionRefusedError` | Service name, start commands, Docker suggestions |
+| `TimeoutError` | Network debugging commands |
+| `ConnectionResetError` | Server-side investigation suggestions |
+| `FileNotFoundError` | Similar files, directory listing, working dir |
+| `PermissionError` | File owner, chmod/chown commands |
+| `KeyError` | Fuzzy match against available keys, `.get()` suggestion |
+| `AttributeError` | Fuzzy match against attributes, NoneType detection |
+| `NameError` | Scope-aware fuzzy matching, import suggestions |
+| `TypeError` | Type mismatch fixes (str+int, not callable, etc.) |
+| `ValueError` | Conversion fixes, unpacking mismatch |
+| `IndexError` | Collection size context, safe access |
+| `ZeroDivisionError` | Zero-valued variable identification |
+| `UnicodeDecodeError` | Encoding suggestions, chardet recommendation |
+| `UnicodeEncodeError` | Encoding alternatives, error handling modes |
+| `RecursionError` | Recursion limit, call chain, base case reminder |
+| `MemoryError` | Memory optimization strategies |
+| `SyntaxError` | Common fix patterns (missing colon, Python 2→3) |
+| `JSONDecodeError` | Error position context, common JSON issues |
+| `StopIteration` | `next()` with default, iterator re-creation |
+| `OSError` | Disk space, file descriptor limits, port conflicts |
+
+## Advanced Usage
+
+### Context Manager
+
+```python
+with failwith.catch(reraise=False):
+    risky_operation()
+```
+
+### Decorator
+
+```python
+@failwith.catch()
+def my_function():
+    risky_operation()
+```
+
+### Custom Suggestions
+
+```python
+@failwith.register(MyDatabaseError)
+def handle_db_error(exc_type, exc_value, exc_tb, config):
+    return failwith.Suggestion(
+        title="Database connection failed",
+        fixes=[
+            "Check DATABASE_URL in your .env file",
+            "Run: docker-compose up -d postgres",
+        ],
+    )
+```
+
+### Configuration
+
+```python
+failwith.install(
+    theme="dark",           # "dark" | "light" | "minimal" | "plain"
+    show_locals=False,      # show local variable values
+    max_suggestions=3,      # limit suggestions shown
+)
+```
+
+## Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `NO_COLOR` | Disable colors (standard) |
+| `FAILWITH_NO_COLOR` | Disable colors |
+| `FAILWITH_FORCE_COLOR` | Force colors even in non-TTY |
+
+## Contributing
+
+Contributions are welcome! The most impactful way to contribute:
+
+1. **Add import mappings** — edit `src/failwith/data/import_map.py`
+2. **Improve suggestions** — edit handlers in `src/failwith/suggestions/`
+3. **Add test cases** — real-world error scenarios in `tests/`
+
+```bash
+git clone https://github.com/yashraj/failwith.git
+cd failwith
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

failwith-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "failwith"
+version = "0.1.0"
+description = "Actionable error intelligence for Python — tells you why errors happen and how to fix them."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Yashraj Aware", email = "yashrajaware2003@gmail.com"},
+]
+keywords = ["errors", "traceback", "debugging", "developer-tools", "exceptions", "diagnostics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+rich = ["rich>=12.0.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Yashraj-Aware/failwith.git"
+Repository = "https://github.com/Yashraj-Aware/failwith"
+Issues = "https://github.com/Yashraj-Aware/failwith/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

failwith-0.1.0/setup.cfg

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

failwith-0.1.0/src/failwith/__init__.py

@@ -0,0 +1,25 @@
+"""
+failwith — Actionable error intelligence for Python.
+
+When Python tells you what broke, failwith tells you why and how to fix it.
+
+Usage:
+    import failwith
+    failwith.install()
+
+That's it. Every unhandled exception now gets actionable fix suggestions.
+"""
+
+__version__ = "0.1.0"
+
+from failwith.core.interceptor import install, uninstall, catch
+from failwith.suggestions.base import Suggestion, register
+
+__all__ = [
+    "install",
+    "uninstall",
+    "catch",
+    "register",
+    "Suggestion",
+    "__version__",
+]

failwith-0.1.0/src/failwith/core/__init__.py

@@ -0,0 +1,2 @@
+# Core package
+

failwith-0.1.0/src/failwith/core/analyzer.py

@@ -0,0 +1,55 @@
+"""
+Exception analyzer — routes exceptions to the appropriate suggestion handler.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from failwith.suggestions import Suggestion, get_handlers
+
+# Import all suggestion modules to trigger registration
+import failwith.suggestions.imports  # noqa: F401
+import failwith.suggestions.connection  # noqa: F401
+import failwith.suggestions.filesystem  # noqa: F401
+import failwith.suggestions.types  # noqa: F401
+import failwith.suggestions.misc  # noqa: F401
+
+
+def analyze_exception(
+    exc_type: Type[BaseException],
+    exc_value: BaseException,
+    exc_tb: Any,
+    config: dict,
+) -> Optional[Suggestion]:
+    """
+    Analyze an exception and return an actionable Suggestion.
+
+    Walks the handler registry (custom first, then built-in) and returns
+    the first non-None suggestion. If no handler matches, returns None.
+    """
+    handlers = get_handlers(exc_type)
+
+    for handler in handlers:
+        try:
+            suggestion = handler(exc_type, exc_value, exc_tb, config)
+            if suggestion and suggestion.fixes:
+                # Trim fixes to max_suggestions
+                max_fixes = config.get("max_suggestions", 10)
+                if len(suggestion.fixes) > max_fixes:
+                    suggestion.fixes = suggestion.fixes[:max_fixes]
+
+                # Attach environment info if not already set
+                if suggestion.env_info is None:
+                    try:
+                        from failwith.utils.env import get_env_summary
+                        suggestion.env_info = get_env_summary()
+                    except Exception:
+                        pass
+
+                return suggestion
+        except Exception:
+            # Individual handler failure must never propagate
+            continue
+
+    return None