Interfaces layer

Public APIs and user-facing interfaces for EzCompiler.

The interfaces layer provides the main entry points for users to interact with the framework, including the primary facade class and command-line interface.

---

EzCompiler

Main facade class that orchestrates the entire compilation, packaging, and distribution workflow.

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

---

CLI functions

Command-line interface functions for interactive project management.

main

Main CLI entry point for the ezcompiler command.

EzCompiler - CLI for Python project compilation and distribution.

Generates configuration files, setup.py, and version files from templates with support for multiple formats (YAML, JSON) and template types.