explain-exception 0.1.3

Explains Python errors in clear English for beginners.

---

# Explain-Exception

**Explain-Exception** is a Python library that explains Python errors in **clear English**, making it easier for beginners and developers to understand what went wrong in their code. It provides both automatic and manual ways to handle exceptions.

---

## Features

- Explains common Python exceptions in simple English
- Provides beginner-friendly explanations
- Shows the full traceback for debugging
- Optional `safe_run` wrapper to automatically explain errors
- Works with any Python function or code block
- Manual `explain` function for detailed control

---

## Installation

### From GitHub (for development/testing)

```bash
git clone https://github.com/yourusername/explain-exception.git
cd explain-exception
pip install -e .

From PyPI

pip install explain-exception

---

Usage

We will use the same function examples to show both safe_run and explain.

1. Using safe_run

safe_run executes any function and automatically explains exceptions if they occur.

from explain_exception import safe_run

def test_error():
    # This will raise a ZeroDivisionError
    x = 10 / 0

safe_run(test_error)

Output:

❌ Error Type: ZeroDivisionError
💬 Message: division by zero
💡 Explanation: You tried to divide a number by zero. Division by zero is undefined.

🔍 Traceback:
Traceback (most recent call last):
  File ".../core.py", line ..., in safe_run
    func()
  File "...", line ..., in test_error
    x = 10 / 0
ZeroDivisionError: division by zero

safe_run is perfect for quick debugging. It automatically explains any exception raised by the function, giving both beginner-friendly explanation and the traceback.

---

2. Using explain manually

The explain function gives you full control over exceptions. Use it when you want to catch the exception yourself and handle it.

from explain_exception import explain

try:
    my_list = [1, 2, 3]
    print(my_list[5])  # Will raise IndexError
except Exception as e:
    print(explain(e))

Output:

❌ Error Type: IndexError
💬 Message: list index out of range
💡 Explanation: You tried to access a position in a list or tuple that doesn’t exist.

explain is ideal for logging, reporting, or handling exceptions in production code while still providing a clear explanation.

---

3. Wrapping any code block

You can also wrap any code block or lambda function with safe_run:

safe_run(lambda: open("nonexistent_file.txt"))

Output:

❌ Error Type: FileNotFoundError
💬 Message: [Errno 2] No such file or directory: 'nonexistent_file.txt'
💡 Explanation: You tried to open a file that doesn't exist or the path is incorrect.

🔍 Traceback: ...

---

Recommended Workflow

1. During development: Use safe_run for quick debugging of any function.
2. For logging or production: Use explain inside a try/except block for detailed control.
3. Extending the library: Add more error types in core.py if needed.

---

Contributing

Contributions are welcome! You can:

• Add explanations for uncommon exceptions
• Improve formatting or message clarity
• Suggest new features

Please follow standard Python best practices and create a pull request for review.

---

License

This project is licensed under the MIT License.

---