pyDefine

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

pyDefine is a pure-Python developer library created by Yahya Mundewadi (Portfolio: 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
• 👨‍💻 Author Portfolio: yahya.in
• 📦 PyPI Package: 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)

pip install --upgrade pydefine

From Source

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:

import pydefine
pydefine.enable()

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

Output:

┌─ ➗ 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

import pydefine

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

3. Quick One-Liner Explanation

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:

# 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 file for details.

Author & Contact 📞

• Author: Yahya Mundewadi
• Portfolio Website: yahya.in
• Project Portal: pydefine.yahya.in
• Email: yahyabuilds@gmail.com
• GitHub: @mdyahhya
• Instagram: @pydefine

✨ Powered by pyDefine ● Created by Yahya Mundewadi (yahya.in) ✨