Metadata-Version: 2.4
Name: hython-cli
Version: 0.1.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Environment :: Console
Summary: Zero-Interruption Python Automation Engine
Author: Hython Labs
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Hython ⚡
### Zero-Interruption Python Automation

> **"Don't ask the developer to fix something that Hython can safely fix itself.  
> And after fixing it: Tell the developer what happened, without making them participate in the process."**

Hython is an automation-first Python environment orchestrator written in **Rust**. It eliminates the friction of managing virtual environments, installing missing dependencies, matching Python versions, and typing routine answers to `[Y/n]` prompts.

---

## The Mental Model

```text
Developer intent (`hython` or `hython run script.py`)
       ↓
Hython inspects project & requirements
       ↓
Hython resolves environment & runtimes
       ↓
Hython fixes safe problems automatically
       ↓
Hython runs the project
       ↓
Hython reports what happened (concise post-action summary)
```

The developer should think:
> *I have a Python project. I want to run it. `hython`. That's it.*

---

## Key Features

- 🚫 **No Routine Prompts:** Never stops execution for safe, deterministic actions like creating `.venv` or installing missing dependencies.
- 🩺 **Self-Healing Environments:** If `.venv` is missing, damaged, or out-of-sync, Hython recreates or synchronizes it seamlessly.
- 🧠 **Automatic IDE & Framework IntelliSense:** Instantly writes `.vscode/settings.json` and `pyrightconfig.json` so editors lock onto the environment. Automatically provisions framework type stubs (e.g. `django-stubs`, `django-stubs-ext`, `pandas-stubs`) so Django ORM autocompletion and hover documentation work out-of-the-box with zero configuration.
- 📦 **Dynamic Import Healing:** Intercepts `ModuleNotFoundError` during both pre-flight static analysis and runtime execution. It maps module names to PyPI packages (e.g. `yaml` → `PyYAML`, `dateutil` → `python-dateutil`, `PIL` → `Pillow`, `psycopg2` → `psycopg2-binary`) and installs them automatically.
- 🎯 **Intelligent Runtime Selection:** Parses `requires-python` (e.g. `>=3.12, <3.14`). If your default interpreter is Python 3.14, Hython discovers or auto-provisions Python 3.13 without manual setup.
- 🤫 **Quiet & Instant When Warm:** Once an environment is ready and synchronized, `hython` introduces near-zero overhead and runs completely silently.
- 📊 **Calm Post-Action Summary:** Reports what was detected, selected, installed, and executed only when actions took place.

---

## Quick Start

### Installation

**Via pip (Recommended):**
```bash
pip install hython-cli
```

**Via Cargo:**
```bash
cargo install --path .
```

**Build from Source:**
```bash
cargo build --release
# Standalone binary located at target/release/hython
```

---

## Usage

### 1. Automatic Project Detection & Execution
In any project folder (Django, FastAPI, Flask, or script-based):
```bash
hython
```
- If Django is detected (`manage.py`): runs `manage.py runserver`.
- If FastAPI is detected (`main.py` with `FastAPI()`): ensures `uvicorn` and runs `uvicorn main:app --reload`.
- If standard entrypoint (`main.py`, `app.py`, `run.py`): executes with project environment.

### 2. Run Any Script with Self-Healing
```bash
hython app.py
```
If `app.py` imports a missing package, Hython resolves it, installs it, runs `app.py`, and displays a clean summary.

### 3. Run Environment Tools
```bash
hython pytest
hython manage.py migrate
hython -m pip list
```

### 4. Add a Dependency Without Prompts
```bash
hython add requests
```
Updates `pyproject.toml` or `requirements.txt` and synchronizes the environment immediately.

### 5. Explicit Synchronization & Status
```bash
hython sync      # Reconciles environment and dependencies
hython status    # Inspects detected project root, manifest, and runtime
```

---

## Architecture

| Module | Responsibility |
| :--- | :--- |
| [`src/main.rs`](file:///Volumes/harsha's%20SSD/Hython/src/main.rs) | CLI entrypoint, argument dispatch, zero-argument project auto-detection |
| [`src/manifest.rs`](file:///Volumes/harsha's%20SSD/Hython/src/manifest.rs) | Inspects `pyproject.toml`, `requirements.txt`, `.python-version`, entry points |
| [`src/runtime.rs`](file:///Volumes/harsha's%20SSD/Hython/src/runtime.rs) | SemVer constraint matching, local Python discovery, standalone runtime provisioning |
| [`src/env.rs`](file:///Volumes/harsha's%20SSD/Hython/src/env.rs) | `.venv` lifecycle, state hashing (`.venv/.hython-state.json`), dependency synchronization |
| [`src/scanner.rs`](file:///Volumes/harsha's%20SSD/Hython/src/scanner.rs) | Fast static AST/regex import scanning for pre-flight missing package detection |
| [`src/resolver.rs`](file:///Volumes/harsha's%20SSD/Hython/src/resolver.rs) | Standard library filter and module-to-PyPI package name mapping |
| [`src/runner.rs`](file:///Volumes/harsha's%20SSD/Hython/src/runner.rs) | Execution supervisor with dynamic runtime `ModuleNotFoundError` interception & self-healing |
| [`src/reporter.rs`](file:///Volumes/harsha's%20SSD/Hython/src/reporter.rs) | Transparent, non-intrusive post-action summary formatter |

---

## License

MIT

