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. It eliminates the friction of managing virtual environments, installing missing dependencies, matching Python versions, configuring IDE settings, and answering routine [Y/n] prompts.

The Mental Model

Developer intent (`hython` or `hython app.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.

Installation

pip install hython-cli

(Or use pipx install hython-cli)

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, corrupted, or out-of-sync, Hython recreates or synchronizes it seamlessly.
• 📦 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 a compatible Python runtime without manual setup.
• 🧠 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.
• 🎨 Automated Code Formatting: Includes hython fmt and configures format-on-save in your editor, enforcing official PEP 8, Black, isort, and framework conventions automatically.
• 🤫 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.

Usage

1. Automatic Project Detection & Execution

In any project folder (Django, FastAPI, Flask, or script-based):

hython

• Django: If manage.py is detected, runs manage.py runserver.
• FastAPI: If FastAPI() is detected in main.py or app.py, ensures uvicorn and runs uvicorn main:app --reload.
• Standard scripts: Automatically finds main.py, app.py, or run.py and executes within the isolated 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. Format Code

hython fmt

Automatically cleans, formats, and sorts imports according to PEP 8 and framework rules.

6. Explicit Synchronization & Status

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

License

MIT License — Hython Labs