Metadata-Version: 2.4
Name: pyOS-kernel
Version: 0.1.0
Summary: Build complete operating systems using Python - compiles to Assembly and Machine Code
Author-email: i87kxxz <i87kxxz@users.noreply.github.com>
Maintainer-email: i87kxxz <i87kxxz@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/i87kxxz/pyOS
Project-URL: Documentation, https://github.com/i87kxxz/pyOS#readme
Project-URL: Repository, https://github.com/i87kxxz/pyOS
Project-URL: Issues, https://github.com/i87kxxz/pyOS/issues
Keywords: operating-system,os,kernel,assembly,x86,bootloader,low-level,systems-programming,qemu,nasm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Assembly
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: System :: Operating System Kernels
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# 🖥️ pyOS

**Build complete operating systems using Python.** Write your OS kernel in Python, and pyOS compiles it to Assembly and Machine Code that runs on real hardware.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<p align="center">
  <img src="https://raw.githubusercontent.com/pyos/pyos/main/docs/screenshot.png" alt="pyOS Screenshot" width="600">
</p>

## ✨ Features

- 🐍 **Write OS in Pure Python** - No Assembly knowledge required
- ⚡ **Compiles to Native Code** - Python → Assembly → Machine Code
- 🎨 **VGA Text Mode** - Full color support (16 colors)
- ⌨️ **Keyboard Support** - PS/2 keyboard driver included
- 🧠 **Memory Management** - GDT, heap allocation, stack management
- 🔧 **QEMU Integration** - Test your OS instantly
- 📦 **Easy Installation** - `pip install pyOS`

## 🚀 Quick Start

### Installation

```bash
pip install pyOS
```

**Requirements:** NASM and QEMU
```bash
# Windows (with chocolatey)
choco install nasm qemu

# Linux
sudo apt install nasm qemu-system-x86

# macOS
brew install nasm qemu
```

### Hello World OS

```python
from pyos import Kernel, Screen

kernel = Kernel(arch="x86")

@kernel.on_boot
def main():
    Screen.clear()
    Screen.set_color("green", "black")
    Screen.print("Hello World!")
    Screen.print("Welcome to my OS!", row=1)

kernel.build("myos.iso")
```

### Run Your OS

```bash
qemu-system-i386 -fda myos.iso
```

## 📖 Documentation

### Kernel

```python
from pyos import Kernel

# Create a kernel targeting x86 architecture
kernel = Kernel(
    arch="x86",           # or "x86_64"
    stack_size=16384,     # 16KB stack
    heap_size=1048576,    # 1MB heap
)

# Register boot functions with priority (lower = runs first)
@kernel.on_boot(priority=0)
def early_boot():
    pass

@kernel.on_boot(priority=1)
def late_boot():
    pass
```

### Screen (VGA Text Mode)

```python
from pyos import Screen

# Clear screen
Screen.clear()

# Set default colors
Screen.set_color("white", "blue")

# Print text
Screen.print("Hello!")
Screen.print("At position", row=5, col=10)
Screen.print("Colored text", color="red", background="black")

# Available colors:
# black, blue, green, cyan, red, magenta, brown, light_gray,
# dark_gray, light_blue, light_green, light_cyan, light_red,
# light_magenta, yellow, white
```

### Building & Running

```python
# Build ISO image
kernel.build("myos.iso")

# Or build raw binary
kernel.build("myos.bin", format="bin")

# Generate Assembly only (for inspection)
asm_code = kernel.compile()
```

## 🎯 Examples

### Multi-Stage Boot

```python
from pyos import Kernel, Screen

kernel = Kernel(arch="x86")

@kernel.on_boot(priority=0)
def init():
    Screen.clear()
    Screen.print("Initializing...", color="cyan")

@kernel.on_boot(priority=1)
def load_drivers():
    Screen.print("[OK] Drivers loaded", row=1, color="green")

@kernel.on_boot(priority=2)
def ready():
    Screen.print("System Ready!", row=3, color="yellow")

kernel.build("myos.iso")
```

### Colorful UI

```python
from pyos import Kernel, Screen

kernel = Kernel(arch="x86")

@kernel.on_boot
def main():
    Screen.clear()
    
    # Draw a header
    Screen.set_color("white", "blue")
    Screen.print("=" * 40, row=0)
    Screen.print("       My Operating System v1.0", row=1)
    Screen.print("=" * 40, row=2)
    
    # System info
    Screen.set_color("green", "black")
    Screen.print("[OK] CPU initialized", row=4)
    Screen.print("[OK] Memory ready", row=5)
    
    # Footer
    Screen.set_color("yellow", "black")
    Screen.print("Press any key to continue...", row=10)

kernel.build("myos.iso")
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Your Python Code                      │
│   @kernel.on_boot                                        │
│   def main():                                            │
│       Screen.print("Hello!")                             │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   pyOS Compiler                          │
│   • Parses Python code                                   │
│   • Captures screen/keyboard operations                  │
│   • Generates x86 Assembly                               │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   NASM Assembler                         │
│   • Converts Assembly to Machine Code                    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Bootable Image                         │
│   • Bootloader (512 bytes)                               │
│   • Kernel binary                                        │
│   • Runs on QEMU or real hardware                        │
└─────────────────────────────────────────────────────────┘
```

## 📁 Project Structure

```
pyOS/
├── pyos/
│   ├── __init__.py
│   ├── kernel.py           # Kernel class and decorators
│   ├── builder.py          # ISO/binary builder
│   ├── emulator.py         # QEMU integration
│   ├── cli.py              # Command-line interface
│   ├── compiler/
│   │   ├── codegen.py      # Python → Assembly
│   │   └── assembler.py    # Assembly → Machine Code
│   ├── drivers/
│   │   ├── screen.py       # VGA text mode driver
│   │   └── keyboard.py     # PS/2 keyboard driver
│   ├── memory/
│   │   ├── manager.py      # Memory allocation
│   │   └── gdt.py          # Global Descriptor Table
│   └── boot/
│       └── bootloader.asm  # x86 bootloader
└── examples/
    ├── hello_world.py
    ├── keyboard_input.py
    └── advanced_os.py
```

## 🛠️ CLI Commands

```bash
# Create new project
pyos new myos

# Build OS
pyos build main.py -o myos.iso

# Run in QEMU
pyos run myos.iso

# Debug mode
pyos debug myos.iso

# Generate Assembly only
pyos asm main.py -o kernel.asm

# Check dependencies
pyos check
```

## 🤝 Contributing

Contributions are welcome! Feel free to:

- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests

## 📄 License

MIT License - feel free to use in your own projects!

## 🙏 Acknowledgments

- NASM - The Netwide Assembler
- QEMU - Open source machine emulator
- OSDev Wiki - Invaluable OS development resources

---

<p align="center">
  Made with ❤️ for OS enthusiasts
</p>

<p align="center">
  <b>Build your dream OS with Python!</b>
</p>
