https://github.com/parmeetbhamrah/whiffpy
Smart Python code explainer & error analyzer for beginners and educators.
https://github.com/parmeetbhamrah/whiffpy
ast error explainer python
Last synced: 4 months ago
JSON representation
Smart Python code explainer & error analyzer for beginners and educators.
- Host: GitHub
- URL: https://github.com/parmeetbhamrah/whiffpy
- Owner: ParmeetBhamrah
- License: mit
- Created: 2025-07-15T20:02:47.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-10-02T21:02:18.000Z (4 months ago)
- Last Synced: 2025-10-02T21:21:06.634Z (4 months ago)
- Topics: ast, error, explainer, python
- Language: Python
- Homepage: https://pypi.org/project/whiffpy/
- Size: 30.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/whiffpy/)
# WhiffPy 🐍💨
**WhiffPy** is a smart Python code explainer and error analyzer designed for beginners, educators, and anyone who wants to understand Python code more deeply. It analyzes code, explains its structure in plain English, and provides actionable, friendly error messages.
---
## 🚀 Features
- Beginner-friendly explanations of code structure using **Python's AST**
- Human-readable **error analysis with suggestions** for common mistakes
- **Safe code execution** with output and error capture
- Flexible **CLI**: analyze files or code snippets, output as text or JSON, save results
- Easy to extend: add new error hints or code patterns
---
## 📦 Installation
### Using pip (recommended for general usage)
WhiffPy **v0.1.2** is available on PyPI. You can install it directly with:
```sh
pip install whiffpy
````
After installation, run the CLI commands:
```sh
whiffpy path/to/file.py
```
### Using Poetry (for development)
Ensure you have **Python 3.9+** and [Poetry](https://python-poetry.org/) installed.
```sh
# Clone the repository and install dependencies
git clone https://github.com/ParmeetBhamrah/whiffpy.git
git clone https://github.com/ParmeetBhamrah/whiffpy.git
cd whiffpy
poetry install
```
---
## 🛠️ Usage
### Command Line Interface
Analyze a Python file:
```sh
whiffpy path/to/file.py
```
Analyze a code snippet directly:
```sh
whiffpy --code "print(1+1)"
```
Explain code structure only (no execution):
```sh
whiffpy path/to/file.py --explain-only
```
Output as JSON:
```sh
whiffpy path/to/file.py --json
```
Save output to a file:
```sh
whiffpy path/to/file.py --save result.txt
```
### Python API
```python
from whiffpy import analyze
code = "x = 1 / 0"
report = analyze(code)
print(report)
```
---
## 📁 Examples
Check the [`examples/`](examples) directory for demos:
* **examples/demo.py** → Basic code execution and error capture
* **examples/demo_analyze.py** → Full analysis with explanations
---
## 🧩 Development Notes
* **Add error hints** → edit `whiffpy/utils.py`
* **Extend code explanations** → edit `whiffpy/explainer.py`
---
## 📂 Project Structure
```
whiffpy/
│── __init__.py # Main API (analyze)
│── cli.py # Command-line interface
│── runner.py # Code execution
│── explainer.py # AST-based code explanations
│── error_analyzer.py # Traceback parsing and suggestions
│── utils.py # Error hints and result formatting
examples/ # Usage examples
README.md
pyproject.toml
poetry.lock
LICENSE
```
---
## 📄 License
WhiffPy is released under the **MIT License**.