Bellande Python Executable

bellande_python_executable is a Python tool that converts Python scripts into standalone executables, similar to PyInstaller but with a simpler architecture and focus on multi-platform operations.

Features

• Convert Python scripts to native executables
• Automatic dependency analysis
• Support for standard library, third-party, and local modules
• Single-file executable output
• Cross-platform support (Linux, Windows, macOS)
• No external dependencies required
• Debug mode for troubleshooting

Installation

git clone <repository-url>
cd bellande_python_executable
pip install -e .

Requirements

• Python 3.7 or higher
• C compiler (GCC on Linux/macOS, MSVC or GCC on Windows)
• Python development headers

Installing Requirements on Linux

# Ubuntu/Debian
sudo apt-get install python3-dev gcc

# CentOS/RHEL/Fedora
sudo dnf install python3-devel gcc

# Or for older versions
sudo yum install python3-devel gcc

Installing Requirements on Windows

• Install Visual Studio Build Tools or Visual Studio Community
• Or install GCC via MinGW-w64

Installing Requirements on macOS

xcode-select --install

Usage

Basic Usage

bellande_python_executable script.py

This will create an executable named script (or script.exe on Windows) in the dist/ directory.

Advanced Usage

bellande_python_executable script.py \
    --output myapp \
    --onefile \
    --exclude tkinter \
    --include requests \
    --add-data "data.txt:." \
    --debug

Command Line Options

• --script - Python script to convert (required)
• --output - Output executable name
• --name - Name of the executable
• --onefile - Create a single executable file (default)
• --windowed - Create windowed application (no console)
• --debug - Enable debug mode
• --exclude - Exclude modules (can be used multiple times)
• --include - Include additional modules (can be used multiple times)
• --add-data - Add data files in format src:dest (can be used multiple times)

Examples

Simple Script

# hello.py
print("Hello, World!")

bellande_python_executable hello.py
./dist/hello

Script with Dependencies

# web_scraper.py
import requests
from bs4 import BeautifulSoup

def main():
    response = requests.get("https://httpbin.org/json")
    print(response.json())

if __name__ == "__main__":
    main()

bellande_python_executable --script web_scraper.py --include requests --include bs4
./dist/web_scraper

Script with Data Files

# config_app.py
import json

def main():
    with open("config.json", "r") as f:
        config = json.load(f)
    print(f"App name: {config['name']}")

if __name__ == "__main__":
    main()

bellande_python_executable --script-file config_app.py --add-data "config.json:."
./dist/config_app

Architecture

bellande_python_executable consists of several modules:

1. main.py - Entry point and command-line interface
2. analyzer.py - Dependency analysis using AST parsing
3. collector.py - Code and resource collection
4. compiler.py - Bytecode compilation and archiving
5. builder.py - Executable generation with C bootstrap
6. utils.py - Utility functions and configuration management

Build Process

1. Analysis Phase - Analyze the main script and discover all dependencies
2. Collection Phase - Gather all required Python files and resources
3. Compilation Phase - Compile Python source to bytecode and create archives
4. Building Phase - Generate C bootstrap code and compile to executable

How It Works

bellande_python_executable creates a C executable that:

1. Embeds Python bytecode and resources as binary data
2. Initializes the Python interpreter at runtime
3. Loads and executes the embedded bytecode
4. Provides a custom import system for bundled modules

The generated executable is completely self-contained and doesn't require Python to be installed on the target system.

Troubleshooting

Common Issues

1. Missing Python headers

   error: Python.h: No such file or directory
   

   Solution: Install Python development packages (python3-dev on Ubuntu)

2. Compiler not found

   gcc: command not found
   

   Solution: Install GCC or appropriate C compiler

3. Import errors in generated executable

   ModuleNotFoundError: No module named 'xyz'
   

   Solution: Use --include xyz to explicitly include the module

Debug Mode

Use --debug flag to enable verbose logging:

bellande_python_executable script.py --debug

This will show detailed information about:

• Discovered dependencies
• Collected files
• Compilation process
• Build steps

Limitations

• Requires C compiler on build system
• Some dynamic imports may not be detected automatically
• Binary size may be large due to embedded Python runtime
• Limited support for Python extensions that require specific loading mechanisms

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Comparison with PyInstaller

Feature	bellande_python_executable	PyInstaller
Dependencies	None	Multiple
Build system	Simple C bootstrap	Complex bundling
Size	Moderate	Smaller
Compatibility	Good	Excellent
Customization	High	Moderate
Learning curve	Low	Moderate

bellande_python_executable is designed to be a simpler, more transparent alternative to PyInstaller with fewer dependencies and easier customization.