Getting Started¶

This guide will help you get started with EzCompiler quickly and easily.

Installation¶

From PyPI (Recommended)¶

pip install ezcompiler

From Source¶

git clone https://github.com/neuraaak/ezcompiler.git
cd ezcompiler
pip install .

Development Installation¶

For contributors and developers:

pip install -e ".[dev]"

This installs EzCompiler in editable mode with all development dependencies (testing, linting, formatting tools).

Requirements¶

Python >= 3.11
PyYAML >= 6.0
One or more compilers:
cx_Freeze >= 7.2.6 (for directory-based builds)
PyInstaller >= 6.11.1 (for single-file executables)
Nuitka >= 2.5.7 (for optimized compilation)

First Steps¶

Basic Project Compilation¶

from ezcompiler import EzCompiler, CompilerConfig

# Create configuration
config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
)

# Initialize compiler
ezcompiler = EzCompiler(config)

# Compile project
ezcompiler.compile_project(compiler="PyInstaller")

Complete Workflow Example¶

from ezcompiler import EzCompiler, CompilerConfig

# Create comprehensive configuration
config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={
        "files": ["config.yaml", "data.json"],
        "folders": ["assets", "templates"]
    },
    output_folder="dist",
    packages=["requests", "pandas"],
    excludes=["debugpy", "pytest"],
)

# Initialize compiler
ezcompiler = EzCompiler(config)

# Full workflow
ezcompiler.compile_project(compiler="PyInstaller")
ezcompiler.zip_compiled_project()
ezcompiler.upload_to_repo(structure="disk", repo_path="./releases")

Configuration Options¶

From Python Code¶

from ezcompiler import CompilerConfig

config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
    compiler="PyInstaller",
    packages=["requests"],
    excludes=["debugpy"],
)

From YAML File¶

Create ezcompiler.yaml:

version: "1.0.0"
project_name: "MyApp"
main_file: "main.py"
output_folder: "dist"
compiler: "PyInstaller"
packages:
  - "requests"
  - "pandas"
excludes:
  - "debugpy"
  - "test"
include_files:
  files:
    - "config.yaml"
  folders:
    - "assets"

Then load it:

from ezcompiler import EzCompiler
import yaml

with open("ezcompiler.yaml") as f:
    config_dict = yaml.safe_load(f)

ezcompiler = EzCompiler.from_dict(config_dict)
ezcompiler.compile_project()

From JSON File¶

Create ezcompiler.json:

{
  "version": "1.0.0",
  "project_name": "MyApp",
  "main_file": "main.py",
  "output_folder": "dist",
  "packages": ["requests", "pandas"]
}

Using the CLI¶

EzCompiler includes a powerful command-line interface:

Initialize Project¶

ezcompiler init

This will guide you through an interactive setup process.

Generate Configuration File¶

ezcompiler generate config --project-name "MyApp" --main-file "main.py"

Generate Setup File¶

ezcompiler generate setup --config ezcompiler.yaml

Generate Version File¶

ezcompiler generate version --config ezcompiler.yaml

Generate Template¶

# Generate config template
ezcompiler generate template --type config --mockup

# Generate setup template
ezcompiler generate template --type setup --mockup

# Generate version template
ezcompiler generate template --type version --mockup

For more details, see the CLI Reference.

Choosing a Compiler¶

EzCompiler supports three compilation backends:

PyInstaller (Single-File Executables)¶

Best for:

Simple distribution
Single-file executables
Quick prototyping

ezcompiler.compile_project(compiler="PyInstaller")

Pros:

Single executable file
Easy distribution
Wide platform support

Cons:

Slower startup time
Larger file size

Cx_Freeze (Directory-Based Builds)¶

Best for:

Large applications
Better performance
Modular distribution

ezcompiler.compile_project(compiler="Cx_Freeze")

Pros:

Faster execution
Better for large apps
More granular control

Cons:

Directory structure (multiple files)
More complex distribution

Nuitka (Optimized Compilation)¶

Best for:

Maximum performance
Native compilation
Production deployments

ezcompiler.compile_project(compiler="Nuitka")

Pros:

Best performance
True native compilation
Smaller memory footprint

Cons:

Longer compilation time
More complex setup

Compiler-Specific Options¶

Cx_Freeze Options¶

config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
    compiler="Cx_Freeze",
    compiler_options={
        "zip_include_packages": ["*"],
        "zip_exclude_packages": ["test", "tkinter"],
        "include_msvcr": True,
        "optimize": 2
    }
)

PyInstaller Options¶

config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
    compiler="PyInstaller",
    compiler_options={
        "log-level": "DEBUG",
        "collect-all": "numpy",
        "onefile": True
    }
)

Nuitka Options¶

config = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
    compiler="Nuitka",
    compiler_options={
        "show-progress": True,
        "enable-plugin": "numpy",
        "onefile": True
    }
)

Including Files and Folders¶

Include Specific Files¶

config = CompilerConfig(
    # ... other options ...
    include_files={
        "files": [
            "config.yaml",
            "data.json",
            "README.txt"
        ],
        "folders": []
    }
)

Include Entire Folders¶

config = CompilerConfig(
    # ... other options ...
    include_files={
        "files": [],
        "folders": [
            "assets",
            "templates",
            "locale"
        ]
    }
)

Mixed Approach¶

config = CompilerConfig(
    # ... other options ...
    include_files={
        "files": ["config.yaml", "data.json"],
        "folders": ["assets", "templates"]
    }
)

Package Management¶

Include Required Packages¶

config = CompilerConfig(
    # ... other options ...
    packages=[
        "requests",
        "pandas",
        "numpy",
        "sqlalchemy"
    ]
)

Exclude Unnecessary Packages¶

config = CompilerConfig(
    # ... other options ...
    excludes=[
        "debugpy",
        "pytest",
        "mypy",
        "ruff"
    ]
)

Packaging and Distribution¶

Create ZIP Archive¶

# After compilation
ezcompiler.zip_compiled_project()

This creates a ZIP archive of the compiled project in the output folder.

Upload to Disk Repository¶

# Upload to local disk
ezcompiler.upload_to_repo(
    structure="disk",
    repo_path="./releases"
)

Upload to HTTP Server¶

# Upload to HTTP server
ezcompiler.upload_to_repo(
    structure="server",
    repo_url="https://releases.mycompany.com/upload",
    credentials={"username": "user", "password": "pass"}
)

Type Hints Support¶

EzCompiler provides full type hints for better IDE support:

from ezcompiler import EzCompiler, CompilerConfig

# Type-annotated configuration
config: CompilerConfig = CompilerConfig(
    version="1.0.0",
    project_name="MyApp",
    main_file="main.py",
    include_files={"files": [], "folders": []},
    output_folder="dist",
)

# Type-safe compiler instance
ezcompiler: EzCompiler = EzCompiler(config)

# Type-safe method calls
result: bool = ezcompiler.compile_project(compiler="PyInstaller")

IDE Benefits¶

With full type hints, you get:

Auto-completion for methods and properties
Type checking with mypy, pyright, or IDE built-in checkers
Inline documentation from docstrings
Error detection before runtime

Next Steps¶

Now that you've set up EzCompiler, explore these resources:

API Reference – Detailed documentation for each module with all classes and methods
CLI Reference – Complete command-line interface documentation
Examples – Complete code examples and use cases
User Guides – In-depth tutorials for configuration and best practices

Troubleshooting¶

Import Error¶

If you encounter import errors:

# Make sure you're importing from 'ezcompiler'
from ezcompiler import EzCompiler, CompilerConfig  # Correct

Compiler Not Found¶

If compilation fails with "compiler not found":

# Install the compiler you want to use
pip install cx-freeze      # For Cx_Freeze
pip install pyinstaller    # For PyInstaller
pip install nuitka         # For Nuitka

Version Compatibility¶

Check your installed version:

import ezcompiler
print(ezcompiler.__version__)  # Should be 2.3.1 or higher

Or from command line:

ezcompiler --version

Compilation Errors¶

If compilation fails:

Check that all required files exist
Verify package names are correct
Check compiler-specific logs in the output folder
Enable debug logging from the host application.

EzCompiler uses the ezplog lib_mode pattern: its printer and logger are passive proxies that produce no output until the host application initializes Ezpl. The library never configures logging on its own.

from ezplog import Ezpl
from ezcompiler import EzCompiler, CompilerConfig

# Host application configures logging once, at the entry point.
Ezpl(level="DEBUG")

ezcompiler = EzCompiler(config)
ezcompiler.compile_project()

# Direct access to the underlying proxies if needed:
ezcompiler.logger.debug("Custom debug message")
ezcompiler.printer.info("Custom console message")

Configuration Errors¶

If configuration is invalid:

from ezcompiler.shared.exceptions import ConfigurationError

try:
    ezcompiler = EzCompiler(config)
    ezcompiler.compile_project()
except ConfigurationError as e:
    print(f"Configuration error: {e}")

Need Help?¶

Documentation: Full API Reference
Examples: Code Examples
Issues: GitHub Issues
Repository: https://github.com/neuraaak/ezcompiler

Ready to compile your Python projects! 🚀