Executable Configuration

class Executable:
    def __init__(
        self,
        script: str | Path,
        init_script: str | Path | None = None,
        base: str | Path | None = None,
        target_name: str | None = None,
        icon: str | Path | None = None,
        shortcut_name: str | None = None,
        shortcut_dir: str | Path | None = None,
        copyright: str | None = None,
        trademarks: str | None = None,
        manifest: str | Path | None = None,
        uac_admin: bool = False,
        uac_uiaccess: bool = False,
    ):
        """
        Create an executable configuration.

        Parameters:
        - script: Path to the main Python script to freeze
        - init_script: Initialization script executed before main script
        - base: Base executable type ("console", "gui", "service") or custom path
        - target_name: Name of the generated executable (without extension)
        - icon: Path to icon file (auto-detects .ico/.icns/.png/.svg extension)
        - shortcut_name: Name for MSI package shortcuts (Windows only)
        - shortcut_dir: Directory for MSI shortcuts (Windows only)
        - copyright: Copyright string for version resource (Windows only)
        - trademarks: Trademarks string for version resource (Windows only)
        - manifest: Path to XML manifest file (Windows only)
        - uac_admin: Request elevation privileges (Windows only)
        - uac_uiaccess: Bypass UI control restrictions (Windows only)
        """

# Base types (built-in)
base = "console"     # Console application (default)
base = "gui"         # GUI application (Windows/macOS)
base = "service"     # Windows service (Windows only)

# Custom base (absolute path)
base = "/path/to/custom/base"

# Key properties
@property
def base(self) -> Path:
    """Path to the base executable template."""

@property  
def icon(self) -> Path | None:
    """Path to icon file with automatic extension detection."""

@property
def init_script(self) -> Path:
    """Path to initialization script."""

@property
def main_script(self) -> Path:
    """Path to main Python script."""

@property
def target_name(self) -> str:
    """Final executable name with platform extension."""

@property
def init_module_name(self) -> str:
    """Name of init module in zip file."""

@property
def main_module_name(self) -> str:
    """Name of main module in zip file."""

# Representation
def __repr__(self) -> str:
    """String representation showing script path."""

from cx_Freeze import Executable

# Basic console application
exe = Executable("main.py")

# GUI application with icon
exe = Executable(
    script="gui_app.py",
    base="gui",
    icon="app_icon",  # Will search for .ico/.icns/.png/.svg
    target_name="MyApplication"
)

# Windows service with metadata
exe = Executable(
    script="service.py",
    base="service",
    target_name="MyService",
    copyright="© 2024 My Company",
    trademarks="MyApp™",
    uac_admin=True
)

# Custom initialization
exe = Executable(
    script="main.py",
    init_script="custom_init.py",
    base="console"
)

def validate_executables(
    dist: Distribution, 
    attr: str, 
    value: list[Executable | dict | str]
) -> None:
    """
    Validate executables attribute for setup() function.

    Parameters:
    - dist: setuptools Distribution object
    - attr: Attribute name being validated
    - value: List of Executable objects, dictionaries, or script strings

    Raises:
    - SetupError: If validation fails

    Notes:
    - Accepts Executable objects, dictionaries (converted to Executable), or strings (script paths)
    - Automatically converts and normalizes input formats
    - Called automatically by setup() function
    """

# Common exceptions during executable configuration
class OptionError(Exception):
    """Raised for invalid executable configuration options."""

# Example error conditions:
# - Base executable not found
# - Invalid target_name (contains path separators)  
# - Icon file not found
# - Invalid init_script path

def validate_executables(dist: Distribution, attr: str, value) -> None:
    """
    Verify that value is a valid executables attribute.
    
    Parameters:
    - dist: setuptools Distribution object
    - attr: Attribute name being validated
    - value: Executables list to validate (Executable objects, dicts, or strings)
    
    Raises:
    - SetupError: If executables list is invalid or contains unsupported types
    
    Accepts:
    - List of Executable objects
    - List of dictionaries with executable configuration
    - List of script paths as strings
    """