build_tools.syllable_walk_tui.services.exporter
===============================================

.. py:module:: build_tools.syllable_walk_tui.services.exporter

.. autoapi-nested-parse::

   Export functionality for Syllable Walker TUI.

   Provides functions for exporting selected names to various formats.



Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_tui.services.exporter.export_names_to_txt
   build_tools.syllable_walk_tui.services.exporter.export_sample_json


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

.. py:function:: export_names_to_txt(names, json_output_path)

   Export names to a plain text file (one name per line).

   The TXT file is written to the same directory as the JSON output,
   using the same base filename with .txt extension.

   :param names: List of names to export
   :param json_output_path: Path to JSON output file (TXT will have same base name)

   :returns: Tuple of (output_path, error_message_or_none)
             - output_path: Path where TXT was written (or would be written on error)
             - error: Error message if failed, None if successful

   .. admonition:: Examples

      >>> names = ["Alara", "Benton", "Carla"]
      >>> txt_path, error = export_names_to_txt(names, "/path/to/names.json")
      >>> if error:
      ...     print(f"Export failed: {error}")
      >>> else:
      ...     print(f"Exported to {txt_path}")


.. py:function:: export_sample_json(names, name_class, selections_dir, sample_size = 5, seed = None)

   Export a random sample of names to a JSON file.

   This helper is used by the TUI renderer screen to create lightweight
   example payloads for API consumers. The output is named
   ``<name_class>_sample.json`` inside the selections directory.

   :param names: Raw selected names to sample from
   :param name_class: Name class identifier (e.g., "first_name")
   :param selections_dir: Directory to write the JSON file into
   :param sample_size: Number of names to include (default: 5)
   :param seed: Optional seed for deterministic sampling (test support)

   :returns: Tuple of (output_path, error_message_or_none)