build_tools.syllable_walk_tui.services.exporter

Export functionality for Syllable Walker TUI.

Provides functions for exporting selected names to various formats.

Functions

export_names_to_txt(names, json_output_path)

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

export_sample_json(names, name_class, selections_dir)

Export a random sample of names to a JSON file.

Module Contents

build_tools.syllable_walk_tui.services.exporter.export_names_to_txt(names, json_output_path)[source]

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.

Parameters:

  • names (list[str]) – List of names to export

  • json_output_path (str) – 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

Return type:

tuple[pathlib.Path, str | None]

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}")
build_tools.syllable_walk_tui.services.exporter.export_sample_json(names, name_class, selections_dir, sample_size=5, seed=None)[source]

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.

Parameters:

  • names (list[str]) – Raw selected names to sample from

  • name_class (str) – Name class identifier (e.g., “first_name”)

  • selections_dir (pathlib.Path) – Directory to write the JSON file into

  • sample_size (int) – Number of names to include (default: 5)

  • seed (int | None) – Optional seed for deterministic sampling (test support)

Returns:

Tuple of (output_path, error_message_or_none)

Return type:

tuple[pathlib.Path, str | None]