Skip to content

Shared layer

Configuration dataclasses and exception hierarchy for EzCompiler.

The shared layer contains data structures and exceptions used across all layers of the framework.

Public imports

All shared symbols are re-exported from the package roots. Always import from ezcompiler.shared (or ezcompiler.shared.exceptions) — never from the underscore-prefixed private modules (e.g. _compiler_config).

Configuration

CompilerConfig

Main configuration dataclass containing all compilation settings.

from ezcompiler.shared import CompilerConfig

CompilerConfig dataclass 

CompilerConfig(version: str, project_name: str, main_file: str, include_files: dict[str, list[str]], output_folder: Path, version_filename: str = 'version_info.txt', project_description: str = '', company_name: str = '', author: str = '', icon: str = '', packages: list[str] = list(), includes: list[str] = list(), excludes: list[str] = list(), console: bool = True, compiler: str = '', repo_destination: RepoDestination = 'disk', release_destination: ReleaseDestination = 'disk', repo_endpoint: str = '', release_endpoint: str = '', repo_public_url: str = '', optimize: bool = True, strip: bool = False, debug: bool = False, tuf_enabled: bool = False, tuf_repo_dir: Path | None = None, tuf_keys_dir: Path | None = None, tuf_expiration_days: dict[str, int] | None = None, installer_enabled: bool = False, installer_output_dir: Path | None = None, installer_iss_path: Path | None = None, installer_per_user: bool = False, compiler_options: dict[str, Any] = dict())

Configuration class for project compilation.

Centralizes all configuration parameters needed for project compilation, version generation, packaging, and distribution. Validates configuration on initialization and provides helper properties for file paths.

Attributes:

Name Type Description
version str

Project version (e.g., "1.0.0")
project_name str

Name of the project
main_file str

Path to main Python file
include_files dict[str, list[str]]

Dict with 'files' and 'folders' lists
output_folder Path

Path to output directory
version_filename str

Name of version info file (default: "version_info.txt")
project_description str

Project description
company_name str

Company or organization name
author str

Project author
icon str

Path to project icon
packages list[str]

List of Python packages to include
includes list[str]

List of modules to include
excludes list[str]

List of modules to exclude
console bool

Show console window in compiled app (default: True)
compiler str

Compiler to use - "" (unset -> prompt), "Cx_Freeze", "PyInstaller", "Nuitka"
repo_destination RepoDestination

TUF repo upload backend - "disk" | "server" | "r2"
release_destination ReleaseDestination

Zip installer upload backend - "disk" | "server"
repo_endpoint str

Endpoint for TUF repo upload (path, URL, or "bucket/prefix")
release_endpoint str

Endpoint for zip installer upload (path or URL)
optimize bool

Optimize code (default: True)
strip bool

Strip debug info (default: False)
debug bool

Enable debug mode (default: False)
optimize bool

Optimize code (compiler-specific, set via the compiler section)
strip bool

Strip debug info (compiler-specific, set via the compiler section)
compiler_options dict[str, Any]

Compiler-specific options dict, populated from the per-compiler section ([tool.ezcompiler.]) that matches the selected compiler (default: {})
tuf_enabled bool

Enable TUF secure release pipeline (default: False)
tuf_repo_dir Path | None

Path to TUF repository directory
tuf_keys_dir Path | None

Path to TUF keys directory
Example

config = CompilerConfig( ... version="1.0.0", ... project_name="MyApp", ... main_file="main.py", ... include_files={"files": ["config.yaml"], "folders": ["lib"]}, ... output_folder=Path("dist") ... ) config_dict = config.to_dict()

version_file property 

version_file: Path

Get the full path to the version file.

Returns:

Name Type Description
Path Path

Full path to version_info.txt in output folder

zip_file_path property 

zip_file_path: Path

Get the path to the zip file.

Uses the project name as the zip filename, placed next to the output folder (e.g., dist/MyApp.zip).

Returns:

Name Type Description
Path Path

Path to the zip archive file

resolved_repo_destination property 

resolved_repo_destination: str | None

Destination résolue pour l'arbre TUF.

resolved_release_destination property 

resolved_release_destination: str | None

Destination résolue pour le zip installeur.

to_dict 

to_dict() -> dict[str, Any]

Convert configuration to dictionary.

Creates a comprehensive dictionary representation of the configuration with nested structures for compilation, upload, and advanced settings. Compiler-specific options (optimize, strip and free-form compiler_options) are emitted under the per-compiler section key matching the selected compiler.

Returns:

Type Description
dict[str, Any]

dict[str, Any]: Configuration as nested dictionary
Example

config = CompilerConfig(...) config_dict = config.to_dict() print(config_dict["version"]) '1.0.0'

from_dict classmethod 

from_dict(config_dict: dict[str, Any]) -> CompilerConfig

Create configuration from dictionary.

Flattens nested structures (compilation, upload, advanced) and creates a new CompilerConfig instance. Handles backward compatibility for 'version_file' key.

Parameters:

Name Type Description Default
config_dict dict[str, Any]

Configuration dictionary with nested structures

 required

Returns:

Name Type Description
CompilerConfig CompilerConfig

New configuration instance

Raises:

Type Description
ConfigurationError

If required fields are missing or invalid
Example

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

CompilationResult

Result type returned by compilation operations.

from ezcompiler.shared import CompilationResult

CompilationResult 

CompilationResult(zip_needed: bool, compiler_name: str, compiler_instance: CompilerPort)

Result of a compilation operation.

Contains information about the compilation result, including whether the output needs to be zipped and the compiler instance used.

Attributes:

Name Type Description
zip_needed

Whether the compiled output needs to be zipped
compiler_name

Name of the compiler used
_compiler_instance

The compiler instance that performed the compilation
Example

result = service.compile(compiler="PyInstaller") if result.zip_needed: ... # Create ZIP archive

Initialize compilation result.

Parameters:

Name Type Description Default
zip_needed bool

Whether output needs to be zipped

 required
compiler_name str

Name of compiler used

 required
compiler_instance CompilerPort

Compiler instance that performed compilation

 required

Exceptions

Base exceptions

EzCompilerError

Base exception class for all EzCompiler errors.

from ezcompiler.shared.exceptions import EzCompilerError

EzCompilerError

Bases: Exception

Base exception for all EzCompiler utils errors.

Service exceptions

Exceptions raised by service layer components.

from ezcompiler.shared.exceptions.services import (
    CompilationError,
    ConfigurationError,
    TemplateServiceError,
    UploaderServiceError,
    CompilerServiceError,
)

CompilationError

Exception raised when compilation fails.

CompilationError

Bases: CompilerServiceError

Raised when project compilation fails.

ConfigurationError

Exception raised when configuration is invalid.

ConfigurationError

Bases: CompilerServiceError

Raised when configuration is invalid or missing.

TemplateServiceError

Exception raised when template processing fails.

TemplateServiceError

Bases: EzCompilerServiceError

Base exception for template service operations.

UploaderServiceError

Exception raised when upload operations fail.

UploaderServiceError

Bases: EzCompilerServiceError

Base exception for uploader service operations.

Conservé pour compatibilité ; UploadError est désormais l'unique classe canonique importée depuis utils/_uploader_exceptions.py (sous EzCompilerError).

CompilerServiceError

Exception raised when compiler service operations fail.

CompilerServiceError

Bases: EzCompilerServiceError

Base exception for compiler service operations.

Utils exceptions

Exceptions raised by utility modules. ConfigError, ZipError, and UploadError are re-exported from ezcompiler.shared.exceptions. The remaining utility-layer exceptions are accessed via ezcompiler.shared.exceptions.utils.

from ezcompiler.shared.exceptions import ConfigError, ZipError, UploadError
from ezcompiler.shared.exceptions.utils import (
    ValidationError,
    FileError,
    TemplateProcessingError,
    CompilerError,
)

ValidationError

Exception raised when validation fails.

ValidationError

Bases: EzCompilerError

Base exception for validation errors.

FileError

Exception raised when file operations fail.

FileError

Bases: EzCompilerError

Base exception for file operation errors.

ConfigError

Exception raised when configuration parsing fails.

ConfigError

Bases: EzCompilerError

Base exception for configuration errors.

ZipError

Exception raised when ZIP operations fail.

ZipError

Bases: EzCompilerError

Base exception for ZIP operation errors.

TemplateProcessingError

Exception raised when template operations fail.

TemplateProcessingError

Bases: EzCompilerError

Base exception for template processing errors.

UploadError

Exception raised when uploader operations fail.

UploadError

Bases: EzCompilerError

Base exception for upload operation errors (canonical).

CompilerError

Exception raised when compiler operations fail.

CompilerError

Bases: EzCompilerError

Base exception for compiler operation errors.

Installer exceptions

Exceptions raised by installer packaging (Inno Setup).

from ezcompiler.shared.exceptions import (
    InstallerError,
    InstallerTypeError,
    InstallerBuildError,
    InstallerConfigError,
    IsccNotFoundError,
)

InstallerError

Base exception for installer packaging errors.

InstallerError

Bases: EzCompilerError

Base exception for installer packaging errors (canonical).

InstallerTypeError

Exception raised when the requested installer type is not supported.

InstallerTypeError

Bases: InstallerError

Raised when the requested installer type is not supported.

IsccNotFoundError

Exception raised when the Inno Setup compiler (ISCC.exe) cannot be located.

IsccNotFoundError

Bases: InstallerError

Raised when the Inno Setup compiler (ISCC.exe) cannot be located.

InstallerBuildError

Exception raised when running ISCC.exe against the .iss script fails.

InstallerBuildError

Bases: InstallerError

Raised when running ISCC.exe against the .iss script fails.

InstallerConfigError

Exception raised when installer configuration is invalid or incomplete.

InstallerConfigError

Bases: InstallerError

Raised when installer configuration is invalid or incomplete.

Release exceptions

Exceptions raised by secure-release (TUF/tufup) operations.

from ezcompiler.shared.exceptions import (
    ReleaseError,
    ReleaserTypeError,
    BundleBuildError,
    SigningKeyError,
    ReleaseConfigError,
)

ReleaseError

Base exception for secure-release operation errors.

ReleaseError

Bases: EzCompilerError

Base exception for secure-release operation errors (canonical).

ReleaserTypeError

Exception raised when the requested releaser type is not supported.

ReleaserTypeError

Bases: ReleaseError

Raised when the requested releaser type is not supported.

BundleBuildError

Exception raised when building the release bundle archive fails.

BundleBuildError

Bases: ReleaseError

Raised when building the release bundle archive fails.

SigningKeyError

Exception raised when signing keys are missing, invalid, or inaccessible.

SigningKeyError

Bases: ReleaseError

Raised when signing keys are missing, invalid, or inaccessible.

ReleaseConfigError

Exception raised when release configuration is invalid or incomplete.

ReleaseConfigError

Bases: ReleaseError

Raised when release configuration is invalid or incomplete.