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

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):

pip install hython-cli

Via Cargo:

cargo install --path .

Build from Source:

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):

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

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

hython pytest
hython manage.py migrate
hython -m pip list

4. Add a Dependency Without Prompts

hython add requests

Updates pyproject.toml or requirements.txt and synchronizes the environment immediately.

5. Explicit Synchronization & Status

hython sync      # Reconciles environment and dependencies
hython status    # Inspects detected project root, manifest, and runtime

---

Architecture

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

---

License

MIT