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

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 the TUF repo and/or the installer zip, as the config says.

Deprecated

Deprecated since 4.1.0, removed in v5. Use publish_update() then publish_release(), or the CLI (ezcompiler publish update then ezcompiler publish release), which asks for confirmation before any irreversible publication.

When release_needed is True, performs two sequential uploads: 1. TUF tree -> <dest>/update/ 2. installer zip -> <dest>/release/ (skipped if repo_destination="r2")

Otherwise, uploads the compiled artifact (unchanged behavior).

Parameters:

Name	Type	Description	Default
`destination`	`str \| None`	Shared override for both destinations.	`None`
`repo_destination`	`RepoDestination \| None`	Override for `config.repo_destination`.	`None`
`release_destination`	`ReleaseDestination \| None`	Override for `config.release_destination`.	`None`
`upload_config`	`dict[str, Any] \| None`	Extra options passed to the uploaders.	`None`

Raises:

Type	Description
`ConfigurationError`	If the project is not initialized.
`UploadError`	If an upload fails.

publish_update ¶

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

Publish the signed TUF tree to the update backend.

Python counterpart of ezcompiler publish update. Only the public part of the tree is transferred; the interactive confirmation stays specific to the CLI, a programmatic call being explicit by nature.

Parameters:

Name	Type	Description	Default
`destination`	`str \| None`	Override for the resolved update destination.	`None`
`repo_destination`	`RepoDestination \| None`	Override for `config.repo_destination`.	`None`
`upload_config`	`dict[str, Any] \| None`	Extra options passed to the uploader.	`None`

Raises:

Type	Description
`ConfigurationError`	If the project is not initialized.
`UploadError`	If the transfer fails.

preflight_release ¶

preflight_release(
    *,
    tag: str | None = None,
    release_destination: ReleaseDestination | None = None,
) -> ReleasePreflight

Run the pre-publication checks and return the recap.

Parameters:

Name	Type	Description	Default
`tag`	`str \| None`	Target tag (default: `v<version>`).	`None`
`release_destination`	`ReleaseDestination \| None`	Override for `config.release_destination`.	`None`

Returns:

Name	Type	Description
`ReleasePreflight`	`ReleasePreflight`	What the publication would do, once every local check has passed.

Raises:

Type	Description
`ConfigurationError`	If the project is not initialized.
`PublishError`	If the platform CLI is missing, not authenticated, or if the tag already exists.
`ReleaseError`	If an enabled installer is missing, or if nothing was built.

publish_release ¶

publish_release(
    *,
    tag: str | None = None,
    title: str | None = None,
    notes: str | None = None,
    prerelease: bool | None = None,
    draft: bool = False,
    destination: str | None = None,
    release_destination: ReleaseDestination | None = None,
    upload_config: dict[str, Any] | None = None,
) -> str | None

Publish the installer and the zip as a release.

Python counterpart of ezcompiler publish release. On a platform (github), creates the release and attaches the artifacts; on a file destination (disk/server/r2), copies the artifacts. The operation is irreversible on the platform side: call preflight_release() first to present a recap.

Parameters:

Name	Type	Description	Default
`tag`	`str \| None`	Release tag (default: `v<version>`).	`None`
`title`	`str \| None`	Title (default: `<project> v<version>`).	`None`
`notes`	`str \| None`	Release body; `None` asks for generated notes.	`None`
`prerelease`	`bool \| None`	Force the pre-release label (default: inferred from the version).	`None`
`draft`	`bool`	Create the release unpublished.	`False`
`destination`	`str \| None`	Override for the resolved file destination.	`None`
`release_destination`	`ReleaseDestination \| None`	Override for `config.release_destination`.	`None`
`upload_config`	`dict[str, Any] \| None`	Extra options passed to the uploader.	`None`

Returns:

Type	Description
`str \| None`	str \| None: The release URL on the platform path, `None` on the file path.

Raises:

Type	Description
`ConfigurationError`	If the project is not initialized.
`PublishError`	If publishing to the platform fails.
`UploadError`	If the file transfer fails.
`ReleaseError`	If an enabled installer is missing, or if nothing was built.

release ¶

release(
    bundle_dir: Path,
    *,
    publish: bool = False,
    required: 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`. Deprecated since 4.1.0 (removed in v5): run `run_pipeline()` then `ezcompiler publish update` / `ezcompiler publish release` instead.	`False`
`required`	`bool`	Mark this version as mandatory for TUF clients.	`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

Initialize the TUF keys/repo from the current config.

Explicit action - never called by run_pipeline().

Returns:

Name	Type	Description
`bool`	`bool`	True if the init ran, False if the keys were already present (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,
    skip_build: bool = False,
    required: 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. Publication is not part of the pipeline — run ezcompiler publish update / ezcompiler publish release 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`
`skip_build`	`bool`	Skip version generation and compilation, and resume from the existing build in `output_folder`	`False`
`required`	`bool`	Mark the released version as mandatory (needs the TUF release stage)	`False`

Raises:

Type	Description
`ConfigurationError`	If project not initialized, or required without a release stage
`CompilationError`	If compilation fails, or no existing build is found when `skip_build` is set
`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)

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, build.py, and version files from templates with support for multiple formats (YAML, JSON) and template types.

Interfaces layer¶

EzCompiler¶

EzCompiler ¶

printer property ¶

logger property ¶

config property ¶

init_project ¶

generate_version_file ¶

generate_setup_file ¶

compile_project ¶

zip_compiled_project ¶

upload ¶

publish_update ¶

preflight_release ¶

publish_release ¶

release ¶

init_release ¶

refresh_release_expiration ¶

generate_updater ¶

run_pipeline ¶

CLI functions¶

main¶

printer `property` ¶

logger `property` ¶

config `property` ¶