errfriendly 3.0.1

Friendly explanations for Python errors

🎯 errfriendly

Turn confusing Python errors into simple, helpful explanations!

---

🚀 Get Started in 30 Seconds

Install

pip install errfriendly

Use

import errfriendly
errfriendly.install()

# That's it! Now your errors look like this:

Before vs After

❌ Before (confusing):

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

✅ After (helpful):

======================================================================
🔍 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.

🔧 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.

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

---

🤖 Want AI-Powered Explanations? (Optional)

Get even smarter, context-aware explanations using ChatGPT:

Step 1: Install with AI support

pip install errfriendly[ai-openai]

Step 2: Set your API key

# Windows (PowerShell)
$env:OPENAI_API_KEY = "sk-your-key-here"

# Mac/Linux
export OPENAI_API_KEY="sk-your-key-here"

Step 3: Enable AI

import errfriendly

errfriendly.install()
errfriendly.enable_ai(backend="openai")

# Now errors include personalized AI explanations!

💡 Tip: Don't have an OpenAI key? The basic errfriendly.install() works great without AI!

---

📚 All Supported Errors

errfriendly explains 23+ common Python errors, including:

Error	Example
TypeError	None[0], "hello" + 5
KeyError	my_dict['missing_key']
IndexError	my_list[100]
ValueError	int("not a number")
AttributeError	None.something()
NameError	Using undefined variables
FileNotFoundError	Opening missing files
ZeroDivisionError	1 / 0
ImportError	Missing packages
And 15+ more...

---

⚙️ Configuration Options

import errfriendly

# Basic install
errfriendly.install()

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

# Log errors to a file
errfriendly.install(log_file="errors.log")

# Disable when done
errfriendly.uninstall()

# Check if installed
print(errfriendly.is_installed())  # True or False

---

🔗 Exception Chain Analysis (v3.0)

When one error causes another, errfriendly shows you the full story:

try:
    data = get_user(user_id)  # Returns None
except TypeError:
    raise ValueError("User lookup failed")  # Chained exception

Output:

🔗 EXCEPTION CHAIN ANALYSIS
======================================================================

🕵️ Exception Investigation Map:

[Primary Error] ValueError: User lookup failed
    ↳ Caused by: [TypeError] 'NoneType' object is not subscriptable

📖 Story:
(1) First, a TypeError occurred → (2) which caused a ValueError

🔧 Fix Strategy:
Focus on the underlying TypeError first. The ValueError is just a wrapper.

---

🌐 AI Backend Options

Backend	Command	Best For
OpenAI	pip install errfriendly[ai-openai]	Best quality
Anthropic	pip install errfriendly[ai-anthropic]	Claude fans
Gemini	pip install errfriendly[ai-gemini]	Free tier available
Ollama	pip install errfriendly[ai-local]	Privacy (runs locally)

# Choose your backend
errfriendly.enable_ai(backend="openai")      # ChatGPT
errfriendly.enable_ai(backend="anthropic")   # Claude
errfriendly.enable_ai(backend="gemini")      # Google Gemini
errfriendly.enable_ai(backend="local")       # Ollama (local)

---

❓ FAQ

Do I need an API key?

No! The basic errfriendly.install() works without any API key. AI is optional.

Will this slow down my code?

No. errfriendly only runs when an error actually happens.

Can I use this in production?

It's designed for development and learning. For production, use proper logging.

Does it work in Jupyter notebooks?

Yes! Just add errfriendly.install() at the top of your notebook.

---

📦 Quick Reference

import errfriendly

# Basic (no API key needed)
errfriendly.install()

# With AI (needs OPENAI_API_KEY)
errfriendly.enable_ai(backend="openai")

# Customize AI
errfriendly.enable_ai(
    backend="openai",
    model="gpt-4o-mini",           # Which model to use
    explain_depth="beginner"       # beginner, intermediate, or expert
)

# Fine-tune settings
errfriendly.configure(
    show_chain_analysis=True,      # Show exception chains
    show_confidence=True,          # Show AI confidence score
)

# Disable
errfriendly.disable_ai()           # Turn off AI
errfriendly.uninstall()            # Remove completely

---

📄 License

MIT License - Use it however you want!

---

Made with ❤️ to help Python beginners understand errors