API Reference¶

Full symbol listings generated from source docstrings via mkdocstrings.

EzCompiler¶

EzCompiler ¶

EzCompiler(config: CompilerConfig | None = None, compiler_service_factory: Callable[[CompilerConfig], CompilerService] | None = None, template_service: TemplateService | None = None, uploader_service: UploaderService | None = None, pipeline_service: PipelineService | None = None)

Main orchestration class for project compilation and distribution.

Coordinates project compilation using modular compilers, version file generation, setup file creation, artifact zipping, and repository upload. Provides high-level API for managing the full build pipeline.

Attributes:

Name	Type	Description
`_config`		CompilerConfig instance with project settings (read via .config property)
`printer`	`_LazyPrinter`	Lazy printer proxy — silent until host app initializes Ezpl
`logger`	`Logger`	Stdlib logger — silent until host app configures logging

Example

config = CompilerConfig(...) compiler = EzCompiler(config) compiler.compile_project() compiler.zip_compiled_project() compiler.upload()

Initialize the EzCompiler orchestrator.

Logging follows the lib_mode pattern: both the printer and logger are passive proxies that produce no output until the host application initializes Ezpl. No logging configuration happens here — that is an application-level concern.

Parameters:

Name	Type	Description	Default
`config`	`CompilerConfig \| None`	Optional CompilerConfig instance (can be set later via init_project)	`None`
`compiler_service_factory`	`Callable[[CompilerConfig], CompilerService] \| None`	Optional factory for CompilerService (for testing)	`None`
`template_service`	`TemplateService \| None`	Optional TemplateService instance (for testing)	`None`
`uploader_service`	`UploaderService \| None`	Optional UploaderService instance (for testing)	`None`
`pipeline_service`	`PipelineService \| None`	Optional PipelineService instance (for testing)	`None`

printer `property` ¶

printer: _LazyPrinter

Get the console printer proxy.

Returns:

Name	Type	Description
`_LazyPrinter`	`_LazyPrinter`	Lazy printer — silent until host app initializes Ezpl

logger `property` ¶

logger: Logger

Get the stdlib logger.

Returns:

Type	Description
`Logger`	logging.Logger: Stdlib logger — silent until host app configures logging

config `property` ¶

config: CompilerConfig | None

Get the current compiler configuration.

Returns:

Type	Description
`CompilerConfig \| None`	CompilerConfig \| None: Current configuration or None if not initialized

init_project ¶

init_project(version: str, project_name: str, main_file: str, include_files: dict[str, list[str]], output_folder: Path | str, **kwargs: Any) -> None

Initialize project configuration.

Creates a CompilerConfig from provided parameters. This is a convenience method for backward compatibility; can also set config directly.

Parameters:

Name	Type	Description	Default
`version`	`str`	Project version (e.g., "1.0.0")	required
`project_name`	`str`	Project name	required
`main_file`	`str`	Path to main Python file	required
`include_files`	`dict[str, list[str]]`	Dict with 'files' and 'folders' lists	required
`output_folder`	`Path \| str`	Output directory path	required
`**kwargs`	`Any`	Additional config options	`{}`

Raises:

Type	Description
`ConfigurationError`	If configuration is invalid

Example

compiler = EzCompiler() compiler.init_project( ... version="1.0.0", ... project_name="MyApp", ... main_file="main.py", ... include_files={"files": [], "folders": []}, ... output_folder="dist" ... )

generate_version_file ¶

generate_version_file(name: str = 'version_info.txt') -> None

Generate version information file.

Uses the configured version information to generate a version file at the specified path. Legacy method for backward compatibility.

Parameters:

Name	Type	Description	Default
`name`	`str`	Version file name (default: "version_info.txt")	`'version_info.txt'`

Raises:

Type	Description
`ConfigurationError`	If project not initialized

Note

Requires project to be initialized first via init_project().

generate_setup_file ¶

generate_setup_file(file_path: Path | str) -> None

Generate setup.py file from template.

Creates a setup.py file using the template system. Legacy method for backward compatibility.

Parameters:

Name	Type	Description	Default
`file_path`	`Path \| str`	Path where to create the setup.py file	required

Raises:

Type	Description
`ConfigurationError`	If project not initialized

Note

Requires project to be initialized first via init_project().

compile_project ¶

compile_project(console: bool = True, compiler: str | None = None) -> None

Compile the project using specified or auto-selected compiler.

Validates configuration, selects compiler if not specified, and executes compilation. Sets _zip_needed based on compiler output type.

Parameters:

Name	Type	Description	Default
`console`	`bool`	Whether to show console window (default: True)	`True`
`compiler`	`str \| None`	Compiler to use or None for auto-selection - "Cx_Freeze": Creates directory with dependencies - "PyInstaller": Creates single executable - "Nuitka": Creates standalone folder or single executable - None: Prompt user for choice or use config default	`None`

Raises:

Type	Description
`ConfigurationError`	If project not initialized
`CompilationError`	If compilation fails

Example

compiler.compile_project(console=False, compiler="PyInstaller")

zip_compiled_project ¶

zip_compiled_project() -> None

Create ZIP archive of compiled project.

Archives the compiled output if needed. Cx_Freeze output is zipped; PyInstaller single-file output is not.

Raises:

Type	Description
`ConfigurationError`	If project not initialized

Note

ZIP creation is optional based on compiler type and settings.

upload ¶

upload(destination: str | None = None, repo_destination: RepoDestination | None = None, release_destination: ReleaseDestination | None = None, upload_config: dict[str, Any] | None = None) -> None

Upload le repo TUF et/ou le zip installeur selon la config.

Quand release_needed est True, effectue deux uploads séquentiels : 1. arbre TUF → <dest>/update/ 2. zip installeur → <dest>/release/ (ignoré si repo_destination="r2")

Sinon, uploade l'artefact compilé (comportement inchangé).

Parameters:

Name	Type	Description	Default
`destination`	`str \| None`	Override commun pour les deux destinations.	`None`
`repo_destination`	`RepoDestination \| None`	Override de `config.repo_destination`.	`None`
`release_destination`	`ReleaseDestination \| None`	Override de `config.release_destination`.	`None`
`upload_config`	`dict[str, Any] \| None`	Options supplémentaires passées aux uploaders.	`None`

Raises:

Type	Description
`ConfigurationError`	Si le projet n'est pas initialisé.
`UploadError`	Si un upload échoue.

release ¶

release(bundle_dir: Path, *, publish: bool = False) -> Path

Package a compiled bundle into a signed TUF repository.

Reads app name, version and tufup directories from the config. When publish is True, the repository tree is transferred via the configured uploader (update_repo_url + repo_destination).

Parameters:

Name	Type	Description	Default
`bundle_dir`	`Path`	Directory containing the compiled application artifacts.	required
`publish`	`bool`	When True, upload the repository/ tree to `update_repo_url`.	`False`

Returns:

Name	Type	Description
`Path`	`Path`	The local `repository/` tree produced by tufup.

Raises:

Type	Description
`ConfigurationError`	If project not initialized.
`ReleaseError`	If release packaging or remote publishing fails.

init_release ¶

init_release() -> bool

Initialise les clés/repo TUF depuis la config courante.

Action explicite — jamais appelée par run_pipeline().

Returns:

Name	Type	Description
`bool`	`bool`	True si init effectuée, False si clés déjà présentes (skip).

Raises:

Type	Description
`ConfigurationError`	If project not initialized.
`ReleaseError`	If TUF initialization fails.

refresh_release_expiration ¶

refresh_release_expiration(*, roles: tuple[str, ...] = ('targets', 'snapshot', 'timestamp'), days: int | None = None) -> Path

Re-sign TUF metadata to extend expiration without a new release.

Native tufup keep-alive for projects updated irregularly: bumps the expiration date of the short-lived roles and re-publishes, so clients keep trusting the repository between releases.

Parameters:

Name	Type	Description	Default
`roles`	`tuple[str, ...]`	Role names to refresh (default: targets/snapshot/timestamp).	`('targets', 'snapshot', 'timestamp')`
`days`	`int \| None`	Days from now. None → the config's `tuf_expiration_days` (or tufup defaults) for each role.	`None`

Returns:

Name	Type	Description
`Path`	`Path`	The local TUF repository directory.

Raises:

Type	Description
`ConfigurationError`	If project not initialized.
`ReleaseError`	If the refresh fails.
`SigningKeyError`	If signing keys are missing.

generate_updater ¶

generate_updater(output_dir: Path | str | None = None, *, patch_config: bool = True) -> list[Path]

Generate auto-update client files for embedding in the compiled bundle.

Generates update.py, settings.py, and copies root.json from the local TUF repository into output_dir.

When patch_config=True (default), the three generated files are added to config.include_files["files"] so they are automatically bundled by the next run_pipeline() call. Call this method BEFORE run_pipeline().

Parameters:

Name	Type	Description	Default
`output_dir`	`Path \| str \| None`	Directory where files are written. Defaults to the directory containing `main_file`.	`None`
`patch_config`	`bool`	If True, add generated file paths to include_files.	`True`

Returns:

Type	Description
`list[Path]`	List of generated file paths [settings.py, update.py, root.json].

Raises:

Type	Description
`ConfigurationError`	If project not initialized.
`UpdaterConfigError`	If tuf_enabled=False or root.json absent.
`UpdaterGenerationError`	If writing files fails.

run_pipeline ¶

run_pipeline(console: bool = True, compiler: str | None = None, skip_zip: bool = False, skip_release: bool = False, skip_installer: bool = False) -> None

Run the build pipeline with visual progress tracking.

Executes version generation, compilation, optional ZIP creation, optional installer build and optional TUF release in sequence with a DynamicLayeredProgress display. Upload is no longer part of the pipeline — call upload() explicitly afterwards.

Parameters:

Name	Type	Description	Default
`console`	`bool`	Whether to show console window (default: True)	`True`
`compiler`	`str \| None`	Compiler to use or None for auto-selection	`None`
`skip_zip`	`bool`	Skip ZIP archive creation	`False`
`skip_release`	`bool`	Skip the TUF release stage	`False`
`skip_installer`	`bool`	Skip the installer build stage	`False`

Raises:

Type	Description
`ConfigurationError`	If project not initialized
`CompilationError`	If compilation fails
`VersionError`	If version file generation fails
`ZipError`	If ZIP creation fails
`ReleaseError`	If the release stage fails
`InstallerError`	If the installer build fails

Example

compiler = EzCompiler(config) compiler.run_pipeline(console=False) compiler.upload()

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)

Ports¶

CompilerPort ¶

Bases: Protocol

Structural contract for a project compiler (Port).

Any object exposing this surface is a valid compiler — no inheritance required. adapters.BaseCompiler and its subclasses conform to it.

Used by: CompilerFactory return type, CompilationResult.compiler_instance.

config `property` ¶

config: CompilerConfig

Configuration the compiler was built with.

zip_needed `property` ¶

zip_needed: bool

Whether the compiled output must be zipped.

compile ¶

compile(console: bool = True) -> None

Compile the project. Raises CompilationError on failure.

get_compiler_name ¶

get_compiler_name() -> str

Human-readable compiler name.

UploaderPort ¶

Bases: Protocol

Structural contract for an artifact uploader (Port).

Any object exposing this surface is a valid uploader — no inheritance required. adapters.BaseUploader and its subclasses conform to it.

Used by: UploaderFactory return type, UploaderService boundaries.

upload ¶

upload(source_path: Path, destination: str) -> None

Upload a file or directory. Raises UploadError on failure.

download ¶

download(remote_source: str, local_dir: Path) -> None

Download a remote tree into local_dir. Raises UploadError.

get_uploader_name ¶

get_uploader_name() -> str

Human-readable uploader name.

ReleaserPort ¶

Bases: Protocol

Structural contract for a secure-release packager (Port).

Any object exposing this surface is a valid releaser — no inheritance required. adapters.BaseReleaser and its subclasses conform to it.

Used by: ReleaserFactory return type, ReleaseService boundaries.

release ¶

release(bundle_dir: Path, app_name: str, version: str, repo_dir: Path, *, patch: bool = True) -> Path

Build and sign the local TUF repository for bundle_dir.

Returns the path to the produced repository/ tree. Raises ReleaseError on failure.

init_keys ¶

init_keys(app_name: str, repo_dir: Path, keys_dir: Path) -> bool

Initialise clés TUF + squelette repo. Idempotent.

Returns True si init effectuée, False si clés déjà présentes (skip). Raises ReleaseError / SigningKeyError on failure.

refresh_expiration ¶

refresh_expiration(app_name: str, repo_dir: Path, keys_dir: Path, *, roles: tuple[str, ...] = ..., days: int | None = None) -> Path

Re-sign metadata to push out expiration without a new release.

Returns the local repository directory. Raises ReleaseError / SigningKeyError on failure.

get_releaser_name ¶

get_releaser_name() -> str

Human-readable releaser name.

Type aliases¶

FilePath ¶

FilePath = str | Path

Type alias for file path inputs.

Accepts

str: String file path
Path: pathlib.Path object

Used by: CompilerConfig, template loaders, file utilities.

CompilerName ¶

CompilerName = str

Type alias for compiler name selection.

Valid values: "" (unset -> prompt), "Cx_Freeze", "PyInstaller", "Nuitka"

Used by: CompilerConfig.compiler, EzCompiler.compile_project().

RepoDestination ¶

RepoDestination = Literal['disk', 'server', 'r2']

Type alias for the TUF repository upload backend.

Valid values: "disk", "server", "r2"

Used by: CompilerConfig.repo_destination, EzCompiler.upload().

ReleaseDestination ¶

ReleaseDestination = Literal['disk', 'server', 'r2']

Type alias for the release zip upload backend.

Valid values: "disk", "server", "r2"

Used by: CompilerConfig.release_destination, EzCompiler.upload().

ReleaseTarget ¶

ReleaseTarget = Literal['tufup']

Type alias for the secure-release backend selection.

Valid values: "tufup"

Used by: CompilerConfig.release_type, ReleaserFactory.

IncludeFiles ¶

IncludeFiles = dict[str, list[str]]

Type alias for the include_files configuration structure.

Expected shape::

{
    "files": ["path/to/file1.txt", "path/to/file2.dll"],
    "folders": ["path/to/assets/", "path/to/data/"],
}

Used by: CompilerConfig.include_files.

JsonMap ¶

JsonMap = dict[str, object]

Type alias for a generic JSON-serializable mapping.

Used by: configuration parsers, template renderers, YAML/JSON loaders.

Exceptions¶

EzCompilerError ¶

Bases: Exception

Base exception for all EzCompiler utils errors.

CompilationError ¶

Bases: CompilerServiceError

Raised when project compilation fails.

ConfigurationError ¶

Bases: CompilerServiceError

Raised when configuration is invalid or missing.

ReleaseError ¶

Bases: EzCompilerError

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

TemplateError ¶

Bases: TemplateServiceError

Raised when template processing or file generation fails.

UpdaterError ¶

Bases: EzCompilerError

Base exception for updater client generation errors (canonical).

UploadError ¶

Bases: EzCompilerError

Base exception for upload operation errors (canonical).

VersionError ¶

Bases: TemplateServiceError

Raised when version file generation fails.

FileOperationError `module-attribute` ¶

FileOperationError = FileError

API Reference¶

EzCompiler¶

EzCompiler ¶

printer property ¶

logger property ¶

config property ¶

init_project ¶

generate_version_file ¶

generate_setup_file ¶

compile_project ¶

zip_compiled_project ¶

upload ¶

release ¶

init_release ¶

refresh_release_expiration ¶

generate_updater ¶

run_pipeline ¶

CompilerConfig¶

CompilerConfig dataclass ¶

version_file property ¶

zip_file_path property ¶

resolved_repo_destination property ¶

resolved_release_destination property ¶

to_dict ¶

from_dict classmethod ¶

Ports¶

CompilerPort ¶

config property ¶

zip_needed property ¶

compile ¶

get_compiler_name ¶

UploaderPort ¶

upload ¶

download ¶

get_uploader_name ¶

ReleaserPort ¶

release ¶

init_keys ¶

refresh_expiration ¶

get_releaser_name ¶

Type aliases¶

FilePath ¶

CompilerName ¶

RepoDestination ¶

ReleaseDestination ¶

ReleaseTarget ¶

IncludeFiles ¶

JsonMap ¶

Exceptions¶

EzCompilerError ¶

CompilationError ¶

ConfigurationError ¶

ReleaseError ¶

TemplateError ¶

UpdaterError ¶

UploadError ¶

VersionError ¶

FileOperationError module-attribute ¶

printer `property` ¶

logger `property` ¶

config `property` ¶

CompilerConfig `dataclass` ¶

version_file `property` ¶

zip_file_path `property` ¶

resolved_repo_destination `property` ¶

resolved_release_destination `property` ¶

from_dict `classmethod` ¶

config `property` ¶

zip_needed `property` ¶

FileOperationError `module-attribute` ¶