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_to_repo("disk", "releases")

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_to_repo ¶

upload_to_repo(structure: Literal['server', 'disk'], repo_path: Path | str, upload_config: dict[str, Any] | None = None) -> None

Upload compiled project to repository.

Uploads the compiled artifact (ZIP or directory) to the specified repository using the appropriate uploader (disk or server).

Parameters:

Name	Type	Description	Default
`structure`	`Literal['server', 'disk']`	Upload type - "server" for HTTP/HTTPS, "disk" for local	required
`repo_path`	`Path \| str`	Repository path or server URL	required
`upload_config`	`dict[str, Any] \| None`	Additional uploader configuration options	`None`

Raises:

Type	Description
`ConfigurationError`	If project not initialized
`EzCompilerError`	If upload structure is invalid

Example

compiler.upload_to_repo("disk", "releases/") compiler.upload_to_repo("server", "https://example.com/upload")

run_pipeline ¶

run_pipeline(console: bool = True, compiler: str | None = None, skip_zip: bool = False, skip_upload: bool = False, upload_structure: Literal['server', 'disk'] | None = None, upload_destination: str | None = None, upload_config: dict[str, Any] | None = None) -> None

Run the full build pipeline with visual progress tracking.

Executes version generation, compilation, optional ZIP creation, and optional upload in sequence with a DynamicLayeredProgress display.

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_upload`	`bool`	Skip upload step	`False`
`upload_structure`	`Literal['server', 'disk'] \| None`	Upload type ("server" or "disk")	`None`
`upload_destination`	`str \| None`	Upload destination path or URL	`None`
`upload_config`	`dict[str, Any] \| None`	Additional uploader configuration	`None`

Raises:

Type	Description
`ConfigurationError`	If project not initialized
`CompilationError`	If compilation fails
`VersionError`	If version file generation fails
`ZipError`	If ZIP creation fails
`UploadError`	If upload fails

Example

compiler = EzCompiler(config) compiler.run_pipeline(console=False, skip_upload=True)

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.

Interfaces Layer¶

EzCompiler¶

EzCompiler ¶

printer property ¶

logger property ¶

config property ¶

init_project ¶

generate_version_file ¶

generate_setup_file ¶

compile_project ¶

zip_compiled_project ¶

upload_to_repo ¶

run_pipeline ¶

CLI Functions¶

main¶

printer `property` ¶

logger `property` ¶

config `property` ¶