build_tools.syllable_walk_tui.services.packager
===============================================

.. py:module:: build_tools.syllable_walk_tui.services.packager

.. autoapi-nested-parse::

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

.. autoapisummary::

   build_tools.syllable_walk_tui.services.packager.SelectionInventory
   build_tools.syllable_walk_tui.services.packager.PackageOptions
   build_tools.syllable_walk_tui.services.packager.PackageResult


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_tui.services.packager.collect_included_files
   build_tools.syllable_walk_tui.services.packager.build_package_metadata
   build_tools.syllable_walk_tui.services.packager.write_metadata_json
   build_tools.syllable_walk_tui.services.packager.scan_selections
   build_tools.syllable_walk_tui.services.packager.package_selections


Module Contents
---------------

.. py:class:: SelectionInventory

   Inventory of selection files discovered in a run directory.

   .. attribute:: run_dir

      Root run directory containing the selections folder

   .. attribute:: selections_dir

      Path to the selections directory

   .. attribute:: selection_json

      JSON selection outputs (excluding meta)

   .. attribute:: selection_txt

      TXT exports associated with selections

   .. attribute:: meta_json

      Meta JSON files (selector metadata)


   .. py:attribute:: run_dir
      :type:  pathlib.Path


   .. py:attribute:: selections_dir
      :type:  pathlib.Path


   .. py:attribute:: selection_json
      :type:  list[pathlib.Path]


   .. py:attribute:: selection_txt
      :type:  list[pathlib.Path]


   .. py:attribute:: meta_json
      :type:  list[pathlib.Path]


.. py:class:: PackageOptions

   Configuration for packaging selection outputs.

   .. attribute:: run_dir

      Run directory containing the selections folder

   .. attribute:: output_dir

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

   .. attribute:: package_name

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

   .. attribute:: include_json

      Whether to include JSON selection outputs

   .. attribute:: include_txt

      Whether to include TXT exports

   .. attribute:: include_meta

      Whether to include selector meta JSON files

   .. attribute:: include_manifest

      Whether to include a generated manifest in the ZIP


   .. py:attribute:: run_dir
      :type:  pathlib.Path


   .. py:attribute:: output_dir
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: package_name
      :type:  str | None
      :value: None



   .. py:attribute:: include_json
      :type:  bool
      :value: True



   .. py:attribute:: include_txt
      :type:  bool
      :value: True



   .. py:attribute:: include_meta
      :type:  bool
      :value: True



   .. py:attribute:: include_manifest
      :type:  bool
      :value: True



.. py:class:: PackageResult

   Result from packaging selections.

   .. attribute:: package_path

      Path to the created ZIP archive

   .. attribute:: included_files

      Files written into the archive

   .. attribute:: manifest

      Manifest payload that was written (if enabled)

   .. attribute:: error

      Error message if the operation failed


   .. py:attribute:: package_path
      :type:  pathlib.Path


   .. py:attribute:: included_files
      :type:  list[pathlib.Path]


   .. py:attribute:: manifest
      :type:  dict | None


   .. py:attribute:: error
      :type:  str | None
      :value: None



.. py:function:: collect_included_files(run_dir, include_json, include_txt, include_meta)

   Collect selection files to include based on include flags.

   :param run_dir: Run directory containing selections/ (or selections/ itself)
   :param include_json: Include JSON selection outputs
   :param include_txt: Include TXT exports
   :param include_meta: Include selector metadata JSON

   :returns: Tuple of (included_files, error_message_or_none)


.. py:function:: build_package_metadata(run_dir, metadata_inputs, included_files, include_flags)

   Build a JSON-serializable metadata payload for the package.

   :param run_dir: Run directory that sourced the selections
   :param metadata_inputs: 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)
   :param included_files: Files included in the package
   :param include_flags: Include flags for json/txt/meta/manifest

   :returns: Metadata dictionary ready for JSON serialization


.. py:function:: write_metadata_json(output_dir, package_name, metadata)

   Write metadata JSON to disk next to the package archive.

   :param output_dir: Directory where the package ZIP is stored
   :param package_name: Package ZIP filename (used to derive JSON filename)
   :param metadata: Metadata dictionary to serialize

   :returns: Tuple of (metadata_path, error_message_or_none)


.. py:function:: scan_selections(run_dir)

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

   :param run_dir: Run directory containing a selections/ subfolder

   :returns: Tuple of (SelectionInventory or None, error message or None)


.. py:function:: package_selections(options)

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

   :param options: Packaging configuration

   :returns: PackageResult with archive path and manifest, or error populated