Metadata-Version: 2.4
Name: pybend
Version: 0.3.6
Summary: Compile Python applications into standalone native binaries
Author: Jude Nii Klemesu Commey
License: MIT License
        
        Copyright (c) 2026 Jude Nii Klemesu Commey
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: binary,compiler,deployment,freezer,standalone
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Rust
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# PyBend 🪶

> Compile Python applications into standalone native binaries that run entirely in volatile memory.

PyBend is a zero-configuration, high-performance Python-to-Native-Binary compiler toolchain. It compiles your Python applications, third-party packages, and native C-extensions into a single, standalone executable — with **zero physical disk I/O at runtime**.

Unlike traditional freezers (PyInstaller, cx_Freeze, Nuitka) that extract dependencies to `/tmp` or `%TEMP%`, PyBend keeps everything in RAM via a custom PEP 451 meta-path importer backed by an embedded Virtual File System.

---

## 🚀 Performance Snapshot

| Metric | PyBend | PyInstaller |
|--------|--------|-------------|
| **Cold-Start Latency** | ~23 ms | ~300–500 ms |
| **Disk I/O at Runtime** | 0 physical writes | Writes to `/tmp` |
| **Binary Size (base)** | ~340 KB (engine) + VFS | ~30 MB+ |
| **Code on Disk** | Never | Extracted to temp |

## 🛠️ How It Works

### 1. AST Tracing & Tree-Shaking
Scans your import graph using Python's `modulefinder`. Only the modules your app actually imports are included — no bloat.

### 2. Optimization Pass (-OO)
All source is compiled to bytecode with assertions and docstrings stripped, yielding 8–15% smaller payloads.

### 3. Dual-Table VFS v2 Layout
Bytecode, native `.so` extensions, and static assets are packed into a structured binary blob:

```
┌──────────────────────────────────────────────────┐
│  BENDVFS BLOB                                     │
├──────────────────────────────────────────────────┤
│  [4B: "BEND" Magic] [4B: Code Entry Count]       │
│  ┌────────────────────────────────────────────┐  │
│  │ Code Module Table                          │  │
│  │  name → (offset, compressed_size,          │  │
│  │          uncompressed_size, is_c_ext)      │  │
│  └────────────────────────────────────────────┘  │
│  [4B: Asset Entry Count]                         │
│  ┌────────────────────────────────────────────┐  │
│  │ Asset Table                                │  │
│  │  path → (offset, compressed_size,          │  │
│  │          uncompressed_size)                │  │
│  └────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────┐  │
│  │ Compressed Payload Pool (zlib DEFLATE)     │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘
```

### 4. RAM-Mapped Execution
- The Rust bootloader memory-maps itself via `memmap2`, locates the VFS by its `BEND` footer signature, and passes it to the embedded Python runtime.
- A `BendMemoryFinder` is injected into `sys.meta_path[0]` per PEP 451 — all imports resolve from RAM.
- C-extensions are written to anonymous `memfd_create` file descriptors and loaded with `dlopen` — the kernel pages them directly from RAM.

---

## 📦 Quick Start

### 1. Install

```bash
pip install pybend
```

### 2. Zero-Config Build

If your project directory contains `main.py` or `app.py`:

```bash
pybend build
```

That's it. The output lands at `./dist/<name>.bin`.

### 3. Explicit Build

```bash
pybend build --entry src/server.py --output deploy/server.bin -O 2
```

### 4. Config-Driven Build (`pybend.toml`)

```toml
[build]
entry_point = "src/main.py"
output_exe = "dist/app.bin"
optimization_level = 2
include_modules = ["hidden_dep"]
exclude_modules = ["test", "unittest"]
include_data = ["config.json", "assets/"]
```

```bash
pybend build
```

### 5. Inspect a Compiled Binary

```bash
pybend inspect dist/app.bin
```

Prints a table of all code and asset entries in the VFS — names, compressed/uncompressed sizes, compression ratios, and module types.

### 6. Build Bootloader from Source

If the pre-built bootloader doesn't match your Python version:

```bash
pybend bootstrap
```

Requires Rust/Cargo. The built template is automatically staged for future use.

### 7. Fetching Embedded Assets at Runtime

Any file listed in `include_data` can be streamed from memory:

```python
import pybend

config = pybend.get_asset("config.json")
template = pybend.get_asset("templates/email.html")
```

No disk access. No extraction. Directly from the VFS.

---

## 🏗️ Project Structure

```
pybend/
├── pyproject.toml              # Hatchling build config
├── bootloader/                 # Rust runtime engine
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs
│       ├── extractor.rs
│       └── bootstrapper.rs
├── pybend/                     # Python build orchestration
│   ├── __init__.py
│   ├── cli.py                  # Click CLI
│   ├── compiler.py             # Pipeline orchestrator
│   ├── config.py               # TOML + CLI config resolution
│   ├── inspector.py            # Binary VFS table parser
│   ├── dependency_resolver.py  # Import tracing + filtering
│   ├── importer.py             # Runtime VFS finder & loaders
│   ├── splicer.py              # Binary tail-splicing
│   ├── vfs_builder.py          # VFS blob construction
│   └── templates/              # Pre-built bootloader binaries
├── docs/                       # MkDocs documentation
├── tests/                      # Test suite
└── .github/workflows/          # CI/CD pipelines
```

---

## ⚙️ Configuration Reference

### CLI Commands

| Command | Description |
|---------|-------------|
| `build` | Compile a Python app into a standalone binary |
| `bootstrap` | Build the bootloader template from Rust source |
| `inspect` | Inspect the VFS table inside a compiled binary |

### CLI Flags (`build`)

| Flag | Shorthand | Description |
|------|-----------|-------------|
| `--entry` | `-e` | Entry point script path |
| `--output` | `-o` | Output executable path |
| `--optimize` | `-O` | Optimization level (0, 1, 2) |
| `--include` | `-i` | Force-include a module |
| `--exclude` | `-x` | Exclude a module |
| `--template` | `-t` | Custom bootloader binary |
| `--config` | `-c` | Custom pybend.toml path |
| `--target` | `-p` | Target platform (`os/arch`, e.g. `linux/x86_64`) |
| `--verbose` | `-v` | Show detailed build output |
| `--quiet` | `-q` | Suppress all non-error output |
| `--no-strip` | | Do not strip debug symbols from output |

### pybend.toml Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `entry_point` | string | auto-discover | Entry script path |
| `output_exe` | string | `dist/<name>.bin` | Output binary path |
| `optimization_level` | int | `2` | Bytecode optimization (0/1/2) |
| `include_modules` | string[] | `[]` | Force-include modules |
| `exclude_modules` | string[] | `[]` | Exclude modules |
| `include_data` | string[] | `[]` | Static file paths to embed |

---

## 🧪 Testing

```bash
# Python test suite (22 tests)
python -m unittest discover -s tests -v

# Rust tests
cd bootloader && RUSTFLAGS="-L lib" cargo test
```

Current test coverage: **22 Python tests + 2 Rust tests — all passing**.

Includes end-to-end compilation + execution tests, C-extension loading via `memfd_create`, VFS structural validation, latency benchmarks, and disk-isolation verification.

---

## 🎯 Target Platform

- **Linux x86_64** (primary, production-tested)

Future targets: `aarch64-unknown-linux-musl`, `x86_64-pc-windows-gnu`, `aarch64-apple-darwin`.

---

## 📜 License

MIT — see [LICENSE](LICENSE).

Copyright (c) 2026 Jude Nii Klemesu Commey
