Skip to content

API Reference

Complete API reference for EzCompiler framework.

Overview

The EzCompiler API provides a comprehensive framework for Python project compilation and distribution. The framework is organized into 4 main layers with complete type hints, Google-style docstrings, and extensive error handling.

Quick Reference

Component Description Documentation
Interfaces Public APIs and user-facing interfaces Main facade and CLI
Services Business logic and orchestration Core service implementations
Adapters Compiler and uploader implementations Concrete adapters and backends
Shared Configuration and exceptions Shared data structures
Types Public type aliases FilePath, CompilerName, etc.
Utils Utility functions and validators File, config, template operations

Import Examples

The main classes can be imported directly from the package:

from ezcompiler import EzCompiler, CompilerConfig

Or from submodules:

from ezcompiler.interfaces import EzCompiler
from ezcompiler.shared import CompilerConfig
from ezcompiler.services import CompilerService
from ezcompiler.adapters import CxFreezeCompiler

Architecture Layers

Interfaces Layer

The interfaces layer provides user-facing APIs:

  • EzCompiler – Main facade class that orchestrates the entire compilation workflow
  • CLIInterface – Interactive command-line interface with rich formatting

View Interfaces Documentation →

Services Layer

The services layer implements business logic and orchestration:

  • CompilerService – Manages compiler selection and compilation process
  • ConfigService – Handles configuration loading and validation
  • PipelineService – Orchestrates compile → zip → upload pipeline
  • TemplateService – Processes templates and generates files
  • UploaderService – Orchestrates upload operations

View Services Documentation →

Adapters Layer

The adapters layer contains concrete implementations for compilation and upload:

Compilers:

  • BaseCompiler – Abstract base class for all compilers
  • CxFreezeCompiler – Cx_Freeze implementation
  • PyInstallerCompiler – PyInstaller implementation
  • NuitkaCompiler – Nuitka implementation
  • CompilerFactory – Factory for creating compiler instances

File Writers:

  • BaseFileWriter – Abstract base class for file writers
  • DiskFileWriter – Local disk file writer

Uploaders:

  • BaseUploader – Abstract base class for all uploaders
  • DiskUploader – Local disk upload backend
  • ServerUploader – HTTP/HTTPS server upload backend
  • UploaderFactory – Factory for creating uploader instances

View Adapters Documentation →

Shared Layer

The shared layer contains common data structures and exceptions:

  • CompilerConfig – Main configuration dataclass
  • CompilationResult – Result type for compilation operations
  • Exception hierarchy – Typed exceptions for error handling

View Shared Documentation →

Types Layer

The types module centralizes public type aliases exported from the top-level package:

  • FilePath – str | Path for file path inputs
  • CompilerName – str for compiler selection ("auto", "Cx_Freeze", "PyInstaller", "Nuitka")
  • UploadTarget – str for upload destination selection ("disk", "server")
  • IncludeFiles – dict[str, list[str]] for the include_files configuration structure
  • JsonMap – dict[str, object] for generic JSON-serializable mappings

View Types Documentation →

Utils Layer

The utils layer provides utility functions and validators:

  • FileUtils – File operations and management
  • ConfigUtils – Configuration parsing (YAML/JSON)
  • TemplateUtils – Template processing
  • ZipUtils – ZIP archive operations
  • Validators – 9 specialized validation modules

View Utils Documentation →

API Design Principles

Type Safety

EzCompiler provides complete type hints for all public APIs:

  • Full type annotations – Python 3.11+ type hints throughout
  • IDE support – Excellent auto-completion and error detection
  • Type checking – Compatible with mypy, pyright, and other type checkers
  • Runtime validation – Type hints used for parameter validation
from ezcompiler import EzCompiler, CompilerConfig

# Type-safe 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
ezcompiler: EzCompiler = EzCompiler(config)

Error Handling

Comprehensive exception hierarchy for granular error handling:

from ezcompiler import EzCompiler
from ezcompiler.shared.exceptions import (
    CompilationError,
    ConfigurationError,
    TemplateError,
    UploadError
)

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

Configuration Management

Flexible configuration with YAML/JSON support:

from ezcompiler import CompilerConfig
import yaml

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

# From YAML file
with open("ezcompiler.yaml") as f:
    config_dict = yaml.safe_load(f)
    config = CompilerConfig.from_dict(config_dict)

Template System

Dynamic file generation with template processing:

from ezcompiler.services import TemplateService

template_service = TemplateService()
content = template_service.process_template(
    template_name="config.yaml",
    variables={"PROJECT_NAME": "MyApp", "VERSION": "1.0.0"}
)

Quick Start Example

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")

# Package and upload
ezcompiler.zip_compiled_project()
ezcompiler.upload_to_repo(structure="disk", repo_path="./releases")

Installation

pip install ezcompiler

For development installation:

git clone https://github.com/neuraaak/ezcompiler.git
cd ezcompiler
pip install -e ".[dev]"

Detailed Documentation

Select a module from the navigation menu or the table above to view detailed documentation with:

  • Complete class and method signatures
  • Parameter descriptions
  • Return value documentation
  • Exception specifications
  • Usage examples
  • Type annotations

Module Documentation

Module Description
Interfaces Public APIs and user-facing interfaces
Services Business logic services and orchestration
Adapters Compiler and uploader concrete implementations
Shared Configuration dataclasses and exception hierarchy
Types Public type aliases (FilePath, CompilerName, …)
Utils Utility functions, file operations, and validators

Need Help?