first commit

README.md

@@ -0,0 +1,236 @@
+# 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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+xcode-select --install
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+bellande_python_executable script.py
+```
+
+This will create an executable named `script` (or `script.exe` on Windows) in the `dist/` directory.
+
+### Advanced Usage
+
+```bash
+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)
+- `-o, --output` - Output executable name
+- `-n, --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
+
+```python
+# hello.py
+print("Hello, World!")
+```
+
+```bash
+bellande_python_executable hello.py
+./dist/hello
+```
+
+### Script with Dependencies
+
+```python
+# 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()
+```
+
+```bash
+bellande_python_executable web_scraper.py --include requests --include bs4
+./dist/web_scraper
+```
+
+### Script with Data Files
+
+```python
+# 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()
+```
+
+```bash
+bellande_python_executable 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:
+
+```bash
+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.