Metadata-Version: 2.4
Name: pydefine
Version: 1.1.3
Summary: Convert Python errors into beginner-friendly explanations
Author-email: Yahya Mundewadi <yahyabuilds@gmail.com>
Maintainer-email: Yahya Mundewadi <yahyabuilds@gmail.com>
License: MIT
Project-URL: Homepage, https://pydefine.yahya.in
Project-URL: Portfolio, https://yahya.in
Project-URL: Documentation, https://github.com/mdyahhya/pydefine#readme
Project-URL: Repository, https://github.com/mdyahhya/pydefine.git
Project-URL: Issues, https://github.com/mdyahhya/pydefine/issues
Project-URL: Changelog, https://github.com/mdyahhya/pydefine/blob/main/CHANGELOG.md
Keywords: error,exception,traceback,beginner,education,debugging,learning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# pyDefine

**Convert Python errors into beginner-friendly explanations and guides you with actionable solutions** ✨

[![Python Version](https://img.shields.io/pypi/pyversions/pydefine.svg)](https://pypi.org/project/pydefine/)
[![PyPI Version](https://img.shields.io/pypi/v/pydefine.svg)](https://pypi.org/project/pydefine/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/mdyahhya/pydefine/workflows/CI/badge.svg)](https://github.com/mdyahhya/pydefine/actions)

**pyDefine** is a pure-Python developer library created by [**Yahya Mundewadi**](https://yahya.in) ([Portfolio: yahya.in](https://yahya.in)). **pyDefine** takes raw Python tracebacks and exceptions and converts them into **clean, beginner-friendly explanations** with actionable fix suggestions and source code context previews. Perfect for students, educators, and developers!

* 🌐 **Official Website:** [pydefine.yahya.in](https://pydefine.yahya.in)
* 👨‍💻 **Author Portfolio:** [yahya.in](https://yahya.in)
* 📦 **PyPI Package:** [pypi.org/project/pydefine](https://pypi.org/project/pydefine/)

---

## Features 🌟

- **164+ Exception Types Covered** - Comprehensive support for built-ins, Web APIs, Databases, Data Science (Pandas/NumPy), Asyncio, Security, and Validation errors.
- **16 Core Categories** - Structured categorization from Syntax, Types, and Math to Database, Network, and Concurrency.
- **Source Code Context Previews** - Automatically reads target source lines and highlights the exact error line with a pointer (`>`).
- **Dynamic Class Inheritance Fallback** - Custom and third-party library exceptions automatically inherit explanations from their base exception classes.
- **Actionable Fix Suggestions** - Every error comes with an immediate, plain-English solution.
- **Multiple Interfaces** - Use as a library (`import pydefine`), CLI tool (`pydefine script.py`), or interactive decoder.
- **Pure Python & Zero Dependencies** - Fast, lightweight, and works anywhere Python runs.
- **Safe Code Execution** - Built-in `safe_run()` for testing code snippets with live error decoding.
- **Production Ready** - 100% test pass rate, type-hinted, and Ruff-linted.

---

## Installation 📦

### From PyPI (Recommended)
```bash
pip install --upgrade pydefine
```

### From Source
```bash
git clone https://github.com/mdyahhya/pydefine.git
cd pydefine
pip install -e .
```

---

## Quick Start 🚀

### 1. Global Exception Hook (Easiest)
Just enable pyDefine once at the start of your script or app:

```python
import pydefine
pydefine.enable()

# Normal code - any uncaught exception will now show a clean card!
number = 10
divisor = 0
result = number / divisor
```

**Output:**
```text
┌─ ➗ Error: ZeroDivisionError ──────────────────────────────────────────
│  Category : Arithmetic & Math
│  Message  : division by zero
│  Location : app.py:6
│
│  Summary  : Division or modulo operation by zero was attempted.
│  Fix      : Check if the divisor is zero before performing division.
│
│  Context  :
│          5 │ divisor = 0
│    >     6 │ result = number / divisor
└───────────────────────────────────────────────────────────── pyDefine ─
```

### 2. Manual Decoding in `try/except`
```python
import pydefine

try:
    data = {"name": "Alice"}
    print(data["email"])
except Exception as e:
    pydefine.quick_decode(e)
```

### 3. Quick One-Liner Explanation
```python
import pydefine

try:
    int("hello")
except Exception as e:
    print(pydefine.explain(e))
    # 🎯 ValueError: An argument received the correct data type but an invalid value.
```

---

## Command Line Interface (CLI) 💻

Run scripts directly through `pydefine` with live diagnostic reports:

```bash
# Run a Python script with error diagnostics
pydefine script.py

# List all 16 categories
pydefine --list

# Filter exceptions by category
pydefine --category "Database & SQL"
pydefine --category "Web & HTTP APIs"

# List all 164+ exceptions
pydefine --list-all
```

---

## Supported Categories 📂

1. **Syntax & Formatting** (`SyntaxError`, `IndentationError`, `TabError`)
2. **Name & Scope** (`NameError`, `UnboundLocalError`, `AttributeError`)
3. **Type & Value** (`TypeError`, `ValueError`, `KeyError`, `IndexError`, `LookupError`, `AssertionError`)
4. **Arithmetic & Math** (`ZeroDivisionError`, `OverflowError`, `FloatingPointError`, `SingularMatrixError`)
5. **File & Operating System** (`FileNotFoundError`, `PermissionError`, `OSError`, `SubprocessError`)
6. **Import & Module** (`ImportError`, `ModuleNotFoundError`, `ZipImportError`)
7. **Runtime & Recursion** (`RuntimeError`, `RecursionError`, `NotImplementedError`, `ExceptionGroup`)
8. **Network & Connection** (`ConnectionError`, `BrokenPipeError`, `TimeoutError`, `URLError`)
9. **Process & Lifecycle** (`MemoryError`, `BufferError`, `KeyboardInterrupt`, `SystemExit`)
10. **Database & SQL** (`DatabaseError`, `OperationalError`, `IntegrityError`, `ProgrammingError`, `SQLAlchemyError`)
11. **Web & HTTP APIs** (`JSONDecodeError`, `HTTPError`, `RequestException`, `RateLimitError`)
12. **Data Science & Arrays** (`EmptyDataError`, `ParserError`, `AxisError`, `LinAlgError`, `ShapeError`)
13. **Async & Concurrency** (`CancelledError`, `InvalidStateError`, `QueueEmpty`, `ThreadError`)
14. **Security & Cryptography** (`SSLError`, `AuthenticationError`, `ForbiddenError`, `JWTError`)
15. **Validation & Serialization** (`ValidationError`, `PydanticCustomError`, `SchemaError`)
16. **Warnings & Deprecations** (`DeprecationWarning`, `RuntimeWarning`, `UserWarning`, `FutureWarning`)

---

## License 📜

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## Author & Contact 📞

* **Author:** **Yahya Mundewadi**
* **Portfolio Website:** [yahya.in](https://yahya.in)
* **Project Portal:** [pydefine.yahya.in](https://pydefine.yahya.in)
* **Email:** [yahyabuilds@gmail.com](mailto:yahyabuilds@gmail.com)
* **GitHub:** [@mdyahhya](https://github.com/mdyahhya)
* **Instagram:** [@pydefine](https://instagram.com/pydefine)

---

**✨ Powered by pyDefine ● Created by [Yahya Mundewadi (yahya.in)](https://yahya.in) ✨**
