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()
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
¶
Get the console printer proxy.
Returns:
| Name | Type | Description |
|---|---|---|
_LazyPrinter |
_LazyPrinter
|
Lazy printer — silent until host app initializes Ezpl |
logger
property
¶
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 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.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 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
¶
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 |
None
|
release_destination
|
ReleaseDestination | None
|
Override for |
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 |
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: |
None
|
release_destination
|
ReleaseDestination | None
|
Override for |
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: |
None
|
title
|
str | None
|
Title (default: |
None
|
notes
|
str | None
|
Release body; |
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 |
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, |
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
¶
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 |
False
|
required
|
bool
|
Mark this version as mandatory for TUF clients. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Path |
Path
|
The local |
Raises:
| Type | Description |
|---|---|
ConfigurationError
|
If project not initialized. |
ReleaseError
|
If release packaging or remote publishing fails. |
init_release
¶
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 |
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 |
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 |
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 |
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)
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: InstallerConfig = InstallerConfig(),
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
|
Release asset destination - disk, server, r2, github, or gitlab |
repo_endpoint |
str
|
Endpoint for TUF repo upload (path, URL, or "bucket/prefix") |
release_endpoint |
str
|
Release endpoint (path, URL, bucket/prefix, or owner/repo) |
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. |
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
¶
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
¶
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 destination for the TUF tree.
resolved_release_destination
property
¶
Resolved destination for the installer zip.
to_dict
¶
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.
compile
¶
Compile the project. Raises CompilationError on failure.
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.
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,
required: bool = False,
) -> Path
Build and sign the local TUF repository for bundle_dir.
required marks the version as mandatory for clients (tufup required).
Returns the path to the produced repository/ tree.
Raises ReleaseError on failure.
init_keys
¶
Initialize TUF keys and the repo skeleton. Idempotent.
Returns True if the init ran, False if the keys were already present (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.
remove_latest
¶
Remove the latest archive (and its patch), then re-sign.
Returns the removed version as spelled in the archive name. Raises ReleaseError / SigningKeyError on failure.
Type aliases¶
FilePath
¶
Type alias for file path inputs.
Accepts
- str: String file path
- Path: pathlib.Path object
Used by: CompilerConfig, template loaders, file utilities.
CompilerName
¶
Type alias for compiler name selection.
Valid values: "" (unset -> prompt), "Cx_Freeze", "PyInstaller", "Nuitka"
Used by: CompilerConfig.compiler, EzCompiler.compile_project().
RepoDestination
¶
Type alias for the TUF repository upload backend.
Valid values: "disk", "server", "r2"
Used by: CompilerConfig.repo_destination, ezcompiler publish update.
ReleaseDestination
¶
Type alias for the release asset destination or publication platform.
Valid values: "disk", "server", "r2", "github", "gitlab"
Used by: CompilerConfig.release_destination, ezcompiler publish release.
ReleaseTarget
¶
Type alias for the secure-release backend selection.
Valid values: "tufup"
Used by: CompilerConfig.release_type, ReleaserFactory.
IncludeFiles
¶
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
¶
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.