explain-exception 0.1.3
Explains Python errors in clear English for beginners.
Requires Python: >=3.8



---

````markdown
# 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

```bash
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.

```python
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.

```python
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`:

```python
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.

```

---

```