errfriendly 0.2.0

Friendly explanations for Python errors

🎯 errfriendly

Friendly, human-readable explanations for Python exceptions.

errfriendly transforms cryptic Python error messages into clear, actionable explanations. Perfect for beginners learning Python or experienced developers who want faster debugging.

---

✨ Features

• 🔍 Clear Explanations: Understand what went wrong in plain English
• 💡 Actionable Suggestions: Get step-by-step guidance on how to fix common errors
• 🎨 Colorful Output: ANSI colors in terminal for better readability
• 📝 Logging Support: Optionally log exceptions to a file
• 🎯 Zero Dependencies: Pure Python, no external packages required
• ⚡ Easy Integration: Just two lines of code to get started
• 🔧 Configurable: Show or hide the original traceback as needed
• 📦 23 Exception Types: Covers all common Python exceptions

---

📦 Installation

pip install errfriendly

For development installation:

git clone https://github.com/infinawaz/errfriendly.git
cd errfriendly
pip install -e ".[dev]"

---

🚀 Quickstart

import errfriendly

# Enable friendly error messages
errfriendly.install()

# That's it! Now all exceptions will show friendly explanations.

---

📸 Before & After

Before (Standard Python)

Traceback (most recent call last):
  File "example.py", line 3, in <module>
    result = data[0]
TypeError: 'NoneType' object is not subscriptable

😕 "What does subscriptable even mean?"

After (With errfriendly)

Traceback (most recent call last):
  File "example.py", line 3, in <module>
    result = data[0]
TypeError: 'NoneType' object is not subscriptable

======================================================================
🔍 FRIENDLY ERROR EXPLANATION
======================================================================

📛 TypeError: Trying to index None

💡 What happened:
   You tried to use square brackets [] on a variable that is None.
   This usually happens when a function returned None instead of a list/dict,
   or when a variable wasn't properly initialized.

🔧 How to fix it:
   1. Check if your variable is None before accessing it: `if my_var is not None:`
   2. Make sure the function you called actually returns something.
   3. Print the variable before this line to see what it contains.
   4. Look for functions that might return None on failure (like .get(), .find(), etc.).

======================================================================

✅ Now you know exactly what to do!

---

🎛️ Configuration

Show Only Friendly Messages (Hide Traceback)

import errfriendly

# Hide the original traceback, show only the friendly explanation
errfriendly.install(show_original_traceback=False)

Disable Friendly Messages

import errfriendly

# Enable friendly messages
errfriendly.install()

# ... your code ...

# Restore original Python behavior
errfriendly.uninstall()

Check Installation Status

from errfriendly.handler import is_installed

if is_installed():
    print("errfriendly is active!")

Enable Logging to File

import errfriendly

# Log exceptions to a file for later review
errfriendly.install(log_file="errors.log")

---

📋 Supported Exception Types

errfriendly provides friendly explanations for:

Exception	Common Causes
TypeError	Wrong type operations, None subscripting, not callable
ValueError	Invalid conversions, unpacking issues
IndexError	List/tuple/string index out of range
KeyError	Missing dictionary keys
AttributeError	Accessing non-existent attributes
NameError	Undefined variables
ImportError	Failed imports
ModuleNotFoundError	Missing modules
ZeroDivisionError	Division by zero
FileNotFoundError	Missing files
PermissionError	Access denied
RecursionError	Infinite recursion
SyntaxError	Invalid syntax
UnicodeDecodeError	Encoding issues
UnicodeEncodeError	Encoding issues
OverflowError	Number too large
MemoryError	Out of memory
StopIteration	Iterator exhausted
AssertionError	Failed assertions
NotImplementedError	Unimplemented features
KeyboardInterrupt	User interruption (Ctrl+C)
TimeoutError	Operation timeouts
ConnectionError	Network connection failures

Plus a fallback handler for any other exception types!

---

🛠️ Advanced Usage

Integration with Logging

import errfriendly
import logging

# Install errfriendly
errfriendly.install()

# Your logging still works normally
logging.basicConfig(level=logging.DEBUG)

In Jupyter Notebooks

# Works in Jupyter too!
import errfriendly
errfriendly.install()

# Exceptions in cells will show friendly messages

Testing Your Error Handling

import errfriendly
from errfriendly.messages import get_friendly_message

# Get a friendly message without raising an exception
message = get_friendly_message(TypeError, TypeError("'int' object is not callable"))
print(message)

---

🧪 Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=errfriendly --cov-report=html

---

🗺️ Roadmap

v0.2.0 ✅ (Current)

• Colored output for terminal (ANSI colors)
• Logging exceptions to file
• Additional exception handlers (5 new types)
• Graceful failure handling

v0.3.0 (Planned)

• Suggestion ranking by likelihood
• Integration with popular IDEs
• Custom error message templates
• Stack trace analysis for better context

v1.0.0 (Goal)

• Stable API
• Comprehensive documentation
• Plugin system for custom handlers
• Integration with error tracking services (Sentry, etc.)
• Internationalization (i18n) support

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs: Open an issue describing the problem
2. Suggest features: Open an issue with your idea
3. Submit PRs: Fork, make changes, and submit a pull request

Development Setup

git clone https://github.com/infinawaz/errfriendly.git
cd errfriendly
pip install -e ".[dev]"
pytest

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💖 Acknowledgments

• Inspired by the Python community's focus on developer experience
• Thanks to all contributors who help make error messages friendlier

---

Made with ❤️ for Python developers everywhere