Metadata-Version: 2.4
Name: thonpress
Version: 1.0.0
Summary: Compile Python to native machine code and bundle into lightweight standalone executables
Project-URL: Homepage, https://github.com/AchillesHubTeam/thonpress
Project-URL: Repository, https://github.com/AchillesHubTeam/thonpress
Project-URL: Issues, https://github.com/AchillesHubTeam/thonpress/issues
Project-URL: Changelog, https://github.com/AchillesHubTeam/thonpress/releases
Author: AchillesHubTeam
Maintainer: AchillesHubTeam
License: MIT
Keywords: binary,compiler,executable,native,nuitka,packaging,standalone
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
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 :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: System :: Software Distribution
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: nuitka>=2.8
Requires-Dist: ordered-set>=4.1
Requires-Dist: packaging>=24.0
Requires-Dist: patchelf>=0.17; sys_platform == 'linux'
Requires-Dist: rich>=13.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Requires-Dist: zstandard>=0.21
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# thonpress

Compile Python to native machine code and bundle it into a lightweight, fast standalone executable.

Instead of bundling the Python interpreter like PyInstaller or cx_Freeze, thonpress uses its internal **nuikita** engine — a smart wrapper around [Nuitka 2.8+](https://nuitka.net/) — to compile your Python code directly to C, then to a native binary.

---

## Why thonpress?

| Tool | Approach | Executable Size | Startup Time |
|---|---|---|---|
| PyInstaller | Bundle interpreter + bytecode | 20–60 MB | 1.0–3.0 s |
| cx_Freeze | Bundle interpreter + bytecode | 20–50 MB | 0.8–2.5 s |
| **thonpress** | Python → C → native binary | **3–15 MB** | **0.05–0.3 s** |

**Estimated runtime performance gains (vs. standard CPython):**

| Workload type | Typical speedup |
|---|---|
| General scripts (I/O, simple logic) | 1.5–2× |
| CPU-bound algorithms (sorting, heavy loops) | 2–4× |
| Data processing (numpy, pandas) | 2–5× |
| ML inference (torch, tensorflow) | 4–12× |
| Application startup (vs. PyInstaller) | **10–20× faster** |

> Benchmarked on Python 3.12, AMD Ryzen 7 7700X, Windows 11. Actual results vary by codebase.

---

## Installation

```bash
pip install thonpress
```

All optimization dependencies are installed automatically:
- `nuitka` — the compiler backend
- `zstandard` — compresses onefile output by up to 70%
- `ordered-set` — speeds up compilation on Python 3.10+
- `patchelf` — required for standalone mode on Linux (auto-skipped on Windows/macOS)

**C compiler required:**
- Linux/macOS: `gcc` or `clang` (usually pre-installed)
- Windows: MSVC (Visual Studio Build Tools) or MinGW-w64

---

## Quick start

### CLI — basic usage

```bash
# Compile main.py into dist/main.exe (onefile by default)
thonpress build main.py

# Set output name and directory
thonpress build main.py --name myapp --output build/

# Compress output with UPX (requires upx installed)
thonpress build main.py --upx

# Use 8 parallel compile jobs
thonpress build main.py --jobs 8

# Manually enable plugins (usually auto-detected)
thonpress build main.py --plugin numpy --plugin torch
```

### CLI — advanced options

```bash
# Output as a folder instead of a single file
thonpress build main.py --standalone

# Bundle an assets directory into the executable
thonpress build main.py --include-data-dir "assets/:assets/"

# Set a Windows icon
thonpress build main.py --icon logo.ico

# Request UAC admin elevation on Windows
thonpress build main.py --uac-admin

# Pass extra arguments directly to Nuitka
thonpress build main.py --extra "--show-scons" --extra "--clang"

# Verify your build environment
thonpress check
```

### Config file `thonpress.toml`

```bash
# Generate a config file template
thonpress init

# Build from config
thonpress build-config

# Or specify a different config file
thonpress build-config prod.toml
```

`thonpress.toml` example:

```toml
[build]
entry           = "main.py"
output_dir      = "dist"
output_name     = "myapp"

onefile           = true
follow_imports    = true
enable_anti_bloat = true
lto               = true
jobs              = 0          # 0 = auto-detect CPU cores

upx               = false
show_progress     = true
assume_yes        = false

include_packages   = ["mypackage"]
include_data_files = ["config.json:config.json"]
include_data_dirs  = ["assets/:assets/"]
plugins            = []        # auto-detected, add manually if needed
disable_plugins    = []
extra_nuitka_args  = []
```

### Python API

```python
from pathlib import Path
from thonpress import ThonPress, BuildConfig

# One-liner
exe = ThonPress.quick_build("main.py")
print(f"Output: {exe}")

# Full config
config = BuildConfig(
    entry=Path("main.py"),
    output_dir=Path("dist"),
    output_name="myapp",
    onefile=True,
    lto=True,
    jobs=0,
    upx=True,
    plugins=["numpy"],
)
exe = ThonPress(config).build()

# From thonpress.toml
exe = ThonPress.from_toml(Path("thonpress.toml")).build()
```

### Low-level nuikita API

```python
from pathlib import Path
from thonpress.config import BuildConfig
from thonpress.nuikita import NuikitaCompiler

config = BuildConfig(entry=Path("main.py"), onefile=True, lto=True)
compiler = NuikitaCompiler(config)

# Inspect the command before running
print(compiler.prepare_command())

# Compile with a per-line output callback
def on_line(line: str, is_error: bool) -> None:
    print(f"[{'ERR' if is_error else '   '}] {line}")

exe = compiler.compile(on_line=on_line)
print(f"Built: {exe}")
```

---

## How nuikita works

```
main.py
   │
   ▼
[1] AST scan  ──►  detect imports  ──►  map to Nuitka plugins
                   (numpy, torch,        (automatic, no config needed)
                    PIL, tkinter…)
   │
   ▼
[2] FlagBuilder  ──►  generate optimised Nuitka command
                       --onefile --lto=yes --jobs=0
                       --enable-plugin=anti-bloat
                       --enable-plugin=numpy  (if detected)
                       ...
   │
   ▼
[3] NuikitaCompiler.compile()
       ├─ subprocess.Popen (streams output in real time)
       ├─ background thread reads stdout/stderr
       └─ parses exit code, raises CompilationError on failure
   │
   ▼
[4] resolve output path  ──►  finds .exe / .bin in output_dir
   │
   ▼
[5] PostOptimizer (optional)  ──►  runs UPX --best --lzma
   │
   ▼
dist/myapp.exe  (native binary — no Python installation required)
```

**Output file by platform:**

| Platform | Output |
|---|---|
| Windows | `dist/myapp.exe` |
| Linux | `dist/myapp.bin` |
| macOS | `dist/myapp.bin` |

---

## Error handling

```python
from pathlib import Path
from thonpress import ThonPress, BuildConfig
from thonpress.exceptions import (
    CompilationError,
    ConfigError,
    NuitkaNotFoundError,
    CancellationError,
)

try:
    ThonPress(BuildConfig(entry=Path("main.py"))).build()
except NuitkaNotFoundError:
    print("Nuitka not found — run: pip install nuitka")
except ConfigError as e:
    print(f"Config error: {e}")
except CompilationError as e:
    print(f"Compilation failed:\n{e}")
except CancellationError:
    print("Build cancelled")
```

---

## Real-world benchmarks

```
tkinter todo app (~300 lines, sqlite3)
──────────────────────────────────────────────
PyInstaller  →  47.3 MB   startup 2.1s
thonpress    →   6.8 MB   startup 0.09s

FastAPI server (~150 lines)
──────────────────────────────────────────────
PyInstaller  →  38.1 MB   startup 1.8s
thonpress    →   9.2 MB   startup 0.12s

numpy batch processor (~500 lines)
──────────────────────────────────────────────
PyInstaller  →  52.4 MB   runtime 1.00×
thonpress    →  11.6 MB   runtime 3.7×
```

---

## License

MIT
