build_tools.syllable_walk_tui.services.packager

Selection packaging service for the Syllable Walker TUI.

This module provides a focused utility for bundling selection outputs from a pipeline run directory into a single distributable archive. The output is a ZIP file containing the selection files and a manifest that summarizes what was included.

Classes

`SelectionInventory`	Inventory of selection files discovered in a run directory.
`PackageOptions`	Configuration for packaging selection outputs.
`PackageResult`	Result from packaging selections.

Functions

`collect_included_files`(run_dir, include_json, ...)	Collect selection files to include based on include flags.
`build_package_metadata`(run_dir, metadata_inputs, ...)	Build a JSON-serializable metadata payload for the package.
`write_metadata_json`(output_dir, package_name, metadata)	Write metadata JSON to disk next to the package archive.
`scan_selections`(run_dir)	Scan a run directory and return an inventory of selection outputs.
`package_selections`(options)	Package selection outputs from a run directory into a ZIP archive.

Module Contents

class build_tools.syllable_walk_tui.services.packager.SelectionInventory[source]

Inventory of selection files discovered in a run directory.

run_dir: Root run directory containing the selections folder

selections_dir: Path to the selections directory

selection_json: JSON selection outputs (excluding meta)

selection_txt: TXT exports associated with selections

meta_json: Meta JSON files (selector metadata)

run_dir: pathlib.Path

selections_dir: pathlib.Path

selection_json: list[pathlib.Path]

selection_txt: list[pathlib.Path]

meta_json: list[pathlib.Path]

class build_tools.syllable_walk_tui.services.packager.PackageOptions[source]

Configuration for packaging selection outputs.

run_dir: Run directory containing the selections folder

output_dir: Destination directory for the package (default: run_dir/packages)

package_name: Optional filename for the ZIP (default: <run_dir>_selections.zip)

include_json: Whether to include JSON selection outputs

include_txt: Whether to include TXT exports

include_meta: Whether to include selector meta JSON files

include_manifest: Whether to include a generated manifest in the ZIP

run_dir: pathlib.Path

output_dir: pathlib.Path | None = None

package_name: str | None = None

include_json: bool = True

include_txt: bool = True

include_meta: bool = True

include_manifest: bool = True

class build_tools.syllable_walk_tui.services.packager.PackageResult[source]

Result from packaging selections.

package_path: Path to the created ZIP archive

included_files: Files written into the archive

manifest: Manifest payload that was written (if enabled)

error: Error message if the operation failed

package_path: pathlib.Path

included_files: list[pathlib.Path]

manifest: dict | None

error: str | None = None

build_tools.syllable_walk_tui.services.packager.collect_included_files(run_dir, include_json, include_txt, include_meta)[source]

Collect selection files to include based on include flags.

Parameters:

run_dir (pathlib.Path) – Run directory containing selections/ (or selections/ itself)
include_json (bool) – Include JSON selection outputs
include_txt (bool) – Include TXT exports
include_meta (bool) – Include selector metadata JSON

Returns:

Tuple of (included_files, error_message_or_none)

Return type:

tuple[list[pathlib.Path], str | None]

build_tools.syllable_walk_tui.services.packager.build_package_metadata(run_dir, metadata_inputs, included_files, include_flags)[source]

Build a JSON-serializable metadata payload for the package.

Parameters:

run_dir (pathlib.Path) – Run directory that sourced the selections
metadata_inputs (dict) – User-supplied metadata fields from the editor (intended_use should be a list of name class identifiers, examples should be a dict keyed by name class)
included_files (Iterable[pathlib.Path]) – Files included in the package
include_flags (dict[str, bool]) – Include flags for json/txt/meta/manifest

Returns:

Metadata dictionary ready for JSON serialization

Return type:

dict

build_tools.syllable_walk_tui.services.packager.write_metadata_json(output_dir, package_name, metadata)[source]

Write metadata JSON to disk next to the package archive.

Parameters:

output_dir (pathlib.Path) – Directory where the package ZIP is stored
package_name (str) – Package ZIP filename (used to derive JSON filename)
metadata (dict) – Metadata dictionary to serialize

Returns:

Tuple of (metadata_path, error_message_or_none)

Return type:

tuple[pathlib.Path, str | None]

build_tools.syllable_walk_tui.services.packager.scan_selections(run_dir)[source]

Scan a run directory and return an inventory of selection outputs.

Parameters:: run_dir (pathlib.Path) – Run directory containing a selections/ subfolder
Returns:: Tuple of (SelectionInventory or None, error message or None)
Return type:: tuple[SelectionInventory | None, str | None]

build_tools.syllable_walk_tui.services.packager.package_selections(options)[source]

Package selection outputs from a run directory into a ZIP archive.

Parameters:: options (PackageOptions) – Packaging configuration
Returns:: PackageResult with archive path and manifest, or error populated
Return type:: PackageResult