Skip to content

core.packaging

Packaging modules: Windows installer generation, cross-platform packaging specs, and debug bundle creation.

Windows Packaging

core.packaging.windows_packaging

Windows desktop app packaging plan.

Provides the scaffolding for Windows-first distribution: PyInstaller/Nuitka backend bundle, installer generation, signing plan, app data directories, bundled resources, local model guidance, and rollback-safe updates.

Components

  • PackagingTarget — enum of packaging formats
  • SigningStrategy — enum of code signing approaches
  • PackagingConfig — configuration for the build
  • BundledResource — description of a bundled resource
  • PackagingPlan — orchestrates the packaging process

BuildArtifact dataclass

Description of a build artifact.

Parameters

name : Artifact name. path : Path to the artifact. size_bytes : Size in bytes (0 if not yet built). checksum : SHA-256 checksum (empty if not yet computed). is_executable : Whether the artifact is executable.

BundledResource dataclass

Description of a resource to bundle with the application.

Parameters

name : Resource name/identifier. source_path : Path to the source resource. dest_path : Destination path within the bundle. is_optional : Whether the resource is optional. description : Human-readable description.

PackagingConfig dataclass

Configuration for the packaging build.

Parameters

target : Packaging format. signing : Code signing strategy. update_strategy : Application update strategy. app_name : Application name. app_version : Application version. app_id : Application identifier. icon_path : Path to application icon. resources : Resources to bundle. include_models : Whether to include local models in the bundle. data_dir : Application data directory.

PackagingPlan

Orchestrates the packaging process.

Parameters

config : Packaging configuration. output_dir : Directory for build artifacts.

add_artifact(artifact: BuildArtifact) -> None

Add a build artifact.

get_installer_spec() -> dict[str, Any]

Generate installer specification.

plan_build() -> list[str]

Generate a build plan (list of steps).

PackagingTarget

Bases: Enum

Packaging formats for Windows distribution.

SigningStrategy

Bases: Enum

Code signing approaches for Windows executables.

UpdateStrategy

Bases: Enum

Application update strategies.

default_packaging_config() -> PackagingConfig

Default packaging configuration for Windows.

default_windows_resources() -> list[BundledResource]

Default resources to bundle for Windows.

Cross-Platform

core.packaging.cross_platform_packaging

Cross-platform packaging plan — Windows, macOS, Linux.

Extends core.windows_packaging with platform-specific packaging targets, data directories, audio backends, keyring integration, GPU acceleration, model storage, auto-update mechanisms, and sandbox behavior. Identifies blockers before implementation and provides a comparison matrix for each capability across all three platforms.

Components

  • Platform — target operating system enum
  • PlatformInstaller — installer format per platform
  • PlatformAudioBackend — audio backend per platform
  • PlatformKeyring — credential storage per platform
  • PlatformGPU — GPU acceleration approach per platform
  • PlatformSandbox — sandbox model per platform
  • PlatformSpec — frozen platform-specific packaging specification
  • Blocker — known blocker for a platform capability
  • CrossPlatformPlan — multi-platform packaging coordinator
  • create_cross_platform_plan() — factory with all three platforms
  • default_platform_specs() — platform matrix defaults

Usage

from core.cross_platform_packaging import create_cross_platform_plan

plan = create_cross_platform_plan()
for spec in plan.platforms:
    print(f"{spec.platform}: {len(spec.blockers)} blockers")

Blocker dataclass

Known blocker for a platform capability.

Parameters

id : Unique identifier (e.g., ""macos-tts-aarch64""). platform : Affected platform. severity : Impact level. title : Short description. description : Detailed explanation and workaround (if any). status : Current resolution status.

BlockerSeverity

Bases: Enum

Severity of a packaging blocker.

CrossPlatformPlan

Coordinates packaging across multiple platforms.

Aggregates platform-specific specs, identifies blockers, generates comparison matrices, and produces build plans for each platform.

Parameters

platforms : List of platform specifications to include in the plan. output_dir : Root directory for all build artifacts (one subdir per platform).

all_release_ready: bool property

True if all platforms have no critical blockers.

critical_blockers: list[Blocker] property

All critical open blockers across platforms.

total_blockers: int property

Total open blockers across all platforms.

get_platform(platform: Platform) -> PlatformSpec | None

Get the spec for a specific platform.

platform_matrix() -> dict[str, dict[str, Any]]

Generate a comparison matrix of capabilities across platforms.

Returns a dict keyed by capability name, each value mapping platform name to the configured value for that capability.

to_markdown() -> str

Generate a markdown comparison report for all platforms.

Platform

Bases: Enum

Supported target operating systems.

PlatformAudioBackend

Bases: Enum

Audio I/O backend per platform.

PlatformGPU

Bases: Enum

GPU acceleration approach per platform.

PlatformInstaller

Bases: Enum

Installer formats per platform.

PlatformKeyring

Bases: Enum

Credential storage per platform.

PlatformSandbox

Bases: Enum

Sandbox model per platform.

PlatformSpec dataclass

Platform-specific packaging specification.

Parameters

platform : Target operating system. installer : Preferred installer format. audio_backend : Primary audio I/O backend. fallback_audio : Fallback audio backend if primary unavailable. keyring : Credential storage backend. gpu : GPU acceleration approach. sandbox : Sandbox model for tool isolation. data_dir : Application data directory convention. app_dir : Application install directory convention. model_cache : Local model cache directory. python_version : Target Python version for this platform. requires_system_deps : System-level dependencies required at runtime. blockers : Known blockers for this platform.

blocker_count: int property

Number of open blockers for this platform.

critical_blockers: list[Blocker] property

Critical-severity blockers that block release.

is_release_ready: bool property

True if no critical open blockers remain.

create_cross_platform_plan(output_dir: str | Path | None = None) -> CrossPlatformPlan

Create a cross-platform packaging plan with all three platforms.

Parameters

output_dir : Root directory for build artifacts. Defaults to ""dist"".

default_platform_specs() -> list[PlatformSpec]

Return default specifications for all three platforms.

run_cli(args: list[str] | None = None) -> None

CLI for cross-platform packaging plan.

Usage::

python -c "from core.cross_platform_packaging import run_cli; run_cli(['--format', 'markdown'])"