ipytool 1.0.0
A lightweight Jupyter-like notebook interface for Python with local code execution
Requires Python: >=3.7
Keywords: jupyter notebook python ide interactive

# 🎯 IPyTool v0.3 - Lightweight Jupyter Alternative

A **lightweight**, browser-based Python notebook tool that looks and works just like Jupyter Notebook. Runs in your local Python environment - **no Pyodide, no PyScript**.

## 📦 Installation

Install via pip:

```bash
pip install ipytool
```

## 🚀 Quick Start

Just run:

```bash
ipytool
```

The notebook interface will automatically open in your default browser at `http://localhost:5000`.

---

## ✨ Key Features

### 🆕 **Version 0.3 Updates**
- **📝 Markdown Cells** - Full rich text documentation support
- **🎨 Beautiful Rendering** - Headings, lists, tables, code blocks
- **✏️ Double-click Edit** - Intuitive markdown editing
- **🔄 Cell Type Toggle** - Easy switch between Code/Markdown

### Version 0.2 Features
- **🔤 Intelligent Autocomplete** - VSCode-style code suggestions (`Ctrl+Space`)
- **⬆️⬇️ Cell Reordering** - Move cells up/down with arrow buttons
- **➕ Flexible Cell Addition** - Insert cells at any position
- **📊 Smart DataFrame Display** - Automatic HTML table rendering
- **📦 Package Installation** - `!pip install` support with progress
- **💬 Interactive Input** - Modal-based `input()` function

### 🎨 **Authentic Jupyter Interface**
- Exact Jupyter Notebook design aur color scheme
- Professional typography aur spacing
- `In [1]:` / `Out[1]:` execution counters
- Hover-based cell toolbars
- Smooth animations aur transitions

### 🚀 **Powerful Code Execution**
- **Stateful execution** - Variables persist across cells (Jupyter-like behavior)
- Full numpy, pandas, aur sabhi installed packages support
- Real-time output display with proper formatting
- Error messages with complete tracebacks
- Execution counter tracking

### ⌨️ **Professional Features**
- **Code Autocomplete** - Python keywords, builtins, aur user-defined suggestions
- **Keyboard shortcuts** (Shift+Enter, Ctrl+Enter, Ctrl+Space)
- **Cell management** - Reorder, insert, delete
- **Kernel restart** capability
- **Notebook save/load** with JSON format

### 🔧 **Enterprise-Grade Design**
- Clean, minimal, professional UI
- Responsive design for all screen sizes
- Smooth state management
- Proper error handling
- Session-based architecture

---

## 🚀 Quick Start

### 1. Install Dependencies
```bash
# Virtual environment already active
source venv/bin/activate

# Install requirements (already done)
pip install -r requirements.txt
```

### 2. Run the Application
```bash
python app.py
```

### 3. Open Browser
Navigate to: **http://localhost:5000**

---

## 📖 Usage Guide

### Basic Operations

#### **Create a New Cell**
- Click `➕` button in toolbar
- Or press `B` key (when not in edit mode)

#### **Run a Cell**
- Click `▶ Run` button
- Or press `Shift+Enter` (runs and selects next cell)
- Or press `Ctrl+Enter` (runs current cell)

#### **Delete a Cell**
- Click `🗑` button in cell toolbar (appears on hover)

#### **Run All Cells**
- Click `▶▶ Run All` button in toolbar

### Advanced Features

#### **Using input() Function**
```python
# This now works perfectly!
name = input("Enter your name: ")
age = input("Enter your age: ")
print(f"Hello {name}, you are {age} years old!")
```
A modal dialog will appear for each `input()` call.

#### **Save Notebook**
1. Enter notebook name in top input field
2. Click `💾` button
3. Notebook saved in `notebooks/` folder as JSON

#### **Load Notebook**
1. Click `📂 Load` button
2. Enter notebook name
3. Notebook loads with all cells and outputs

#### **Restart Kernel**
1. Click `⟳ Restart` button
2. All variables cleared
3. New session created

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Shift+Enter` | Run cell and select next |
| `Ctrl+Enter` | Run current cell |
| `Tab` | Indent code (in cell) |
| `B` | Insert cell below |

---

## 🧪 Testing Examples

### Example 1: NumPy & Pandas
```python
# Cell 1
import numpy as np
import pandas as pd

arr = np.arange(10)
df = pd.DataFrame({
    "values": arr,
    "squared": arr ** 2
})
print(df)
```

```python
# Cell 2 - Variables persist!
total = df["squared"].sum()
print(f"Total: {total}")
```

### Example 2: Interactive Input
```python
# Cell 1
name = input("What's your name? ")
age = int(input("What's your age? "))

print(f"\nHello {name}!")
print(f"In 10 years, you'll be {age + 10} years old.")
```

### Example 3: Data Analysis
```python
# Cell 1
import pandas as pd
import numpy as np

# Create sample data
data = pd.DataFrame({
    'product': ['A', 'B', 'C', 'D'],
    'sales': [100, 150, 200, 175],
    'profit': [20, 35, 50, 40]
})

print(data)
```

```python
# Cell 2 - Analyze the data
data['profit_margin'] = (data['profit'] / data['sales']) * 100
print("\nWith Profit Margins:")
print(data)

print(f"\nAverage Profit Margin: {data['profit_margin'].mean():.2f}%")
```

---

## 📁 Project Structure

```
pyide/
├── app.py              # Flask backend with session management
├── requirements.txt    # Python dependencies
├── static/
│   ├── index.html     # Jupyter-style UI
│   ├── main.js        # Frontend logic with input() support
│   └── styles.css     # Professional Jupyter styling
├── notebooks/         # Saved notebooks (JSON format)
├── venv/             # Python virtual environment
└── README.md         # This file
```

---

## 🔧 Technical Architecture

### Backend (Flask)
- **Session Management**: UUID-based sessions with isolated namespaces
- **Code Execution**: `exec()` with proper stdout/stderr capture
- **Input Handling**: Interactive input() support with callback mechanism
- **State Persistence**: Variables persist across cells within same session
- **Error Handling**: Full traceback capture and display

### Frontend (Vanilla JS)
- **Cell Management**: Dynamic cell creation/deletion with execution counters
- **Input Modal**: Beautiful dialog for `input()` function calls
- **Keyboard Shortcuts**: Jupyter-like keyboard navigation
- **Real-time Updates**: Async execution with loading states
- **Session Tracking**: Maintains connection to backend session

### Storage
- Notebooks saved as JSON in `notebooks/` folder
- Contains: cell code, outputs, execution counts
- Easy to version control and share

---

## 🎨 Design Philosophy

Yeh tool **enterprise-grade software** ki tarah design kiya gaya hai:

1. ✅ **Professional Look** - Exact Jupyter Notebook appearance
2. ✅ **Clean Code** - Modular, well-commented, maintainable
3. ✅ **User Experience** - Smooth interactions, helpful feedback
4. ✅ **Reliability** - Proper error handling, state management
5. ✅ **Performance** - Efficient rendering, async operations
6. ✅ **Extensibility** - Easy to add new features

---

## 🐛 Troubleshooting

### Port Already in Use
```bash
# Find and kill process on port 5000
lsof -ti:5000 | xargs kill -9

# Or use different port
# Edit app.py: app.run(..., port=5001)
```

### Module Not Found
```bash
# Ensure virtual environment is active
source venv/bin/activate

# Reinstall requirements
pip install -r requirements.txt
```

### Session Lost
- Click `⟳ Restart` button to create new session
- Or refresh the page

---

## 🚀 Future Enhancements

Possible improvements for even more professional feel:

- [ ] Markdown cells support
- [ ] Rich output (plots, images, HTML)
- [ ] Code syntax highlighting
- [ ] Auto-completion
- [ ] Cell output collapsing
- [ ] Export to .ipynb format
- [ ] Multiple kernel support
- [ ] Real-time collaboration

---

## 📝 Notes

- **Security**: Yeh tool sirf local use ke liye hai. Production deployment ke liye proper security measures add karein.
- **Python Environment**: Same Python environment use hota hai jahan Flask run ho raha hai.
- **Browser Support**: Modern browsers (Chrome, Firefox, Edge, Safari) mein best kaam karta hai.

---

## 👨‍💻 Developer Notes

Code quality professional standards follow karta hai:

- **Backend**: Clean Flask routes with proper error handling
- **Frontend**: Modular JavaScript with clear function separation  
- **Styling**: Professional CSS with Jupyter-matching design
- **Documentation**: Extensive comments and docstrings

---

## 🎉 Enjoy Coding!

Ab aap ek **professional Jupyter Notebook** experience enjoy kar sakte hain apne local machine par! 🚀

**Happy Coding!** 💻✨