build_tools.tui_common.interactive

Shared interactive mode utilities for syllable extractors.

This module provides common interactive mode prompts and UI helpers used by both pyphen and NLTK syllable extractors.

Usage:

from build_tools.tui_common.interactive import (
    prompt_extraction_settings,
    prompt_input_file,
    print_banner,
    print_section,
)

# Display tool banner
print_banner("PYPHEN SYLLABLE EXTRACTOR", [
    "This tool extracts syllables using dictionary-based hyphenation.",
    "Output is saved to _working/output/ by default.",
])

# Get extraction settings
min_len, max_len = prompt_extraction_settings(
    default_min=2,
    default_max=8,
)

# Get input file
input_path = prompt_input_file()

Functions

`print_banner`(title, description_lines[, width])	Print a formatted banner with title and description.
`print_section`(title[, width])	Print a section header.
`prompt_integer`(prompt_text, default[, min_value, ...])	Prompt for an integer value with validation.
`prompt_extraction_settings`([default_min, default_max, ...])	Prompt for min/max syllable length extraction settings.
`prompt_input_file`([prompt_text])	Prompt for an input file path with tab completion.
`print_extraction_complete`(syllables_path, ...)	Print extraction completion message with output paths.

Module Contents

build_tools.tui_common.interactive.print_banner(title, description_lines, width=70)[source]

Print a formatted banner with title and description.

Parameters:

title (str) – Main title text (displayed in all caps)
description_lines (list[str]) – List of description lines to display
width (int) – Banner width in characters (default: 70)

Example

>>> print_banner("MY TOOL", [
...     "This tool does something useful.",
...     "Output is saved to output/ by default.",
... ])
======================================================================
MY TOOL
======================================================================

This tool does something useful. Output is saved to output/ by default. ======================================================================

build_tools.tui_common.interactive.print_section(title, width=70)[source]

Print a section header.

Parameters:

title (str) – Section title text
width (int) – Section width in characters (default: 70)

Example

>>> print_section("EXTRACTION SETTINGS")
----------------------------------------------------------------------
EXTRACTION SETTINGS
----------------------------------------------------------------------

build_tools.tui_common.interactive.prompt_integer(prompt_text, default, min_value=1, max_value=None, compare_to=None, compare_label='minimum')[source]

Prompt for an integer value with validation.

Parameters:

prompt_text (str) – Text to display in the prompt
default (int) – Default value if user presses Enter
min_value (int) – Minimum allowed value (default: 1)
max_value (int | None) – Maximum allowed value (optional)
compare_to (int | None) – Value that this must be >= (for max > min validation)
compare_label (str) – Label for compare_to value in error message

Returns:

Validated integer value

Return type:

int

Example

>>> min_len = prompt_integer(
...     "Minimum syllable length",
...     default=2,
...     min_value=1,
... )
>>> max_len = prompt_integer(
...     "Maximum syllable length",
...     default=8,
...     min_value=1,
...     compare_to=min_len,
...     compare_label="minimum",
... )

build_tools.tui_common.interactive.prompt_extraction_settings(default_min=2, default_max=8, min_label='Minimum syllable length', max_label='Maximum syllable length')[source]

Prompt for min/max syllable length extraction settings.

Parameters:

default_min (int) – Default minimum syllable length
default_max (int) – Default maximum syllable length
min_label (str) – Label for minimum prompt
max_label (str) – Label for maximum prompt

Returns:

Tuple of (min_len, max_len)

Return type:

tuple[int, int]

Example

>>> print_section("EXTRACTION SETTINGS")
>>> min_len, max_len = prompt_extraction_settings()
>>> print(f"✓ Settings: syllables between {min_len}-{max_len} characters")

build_tools.tui_common.interactive.prompt_input_file(prompt_text="Enter input file path (or 'quit' to exit): ")[source]

Prompt for an input file path with tab completion.

Includes: - Tab completion hint (if readline available) - Home directory expansion (~) - File existence validation - ‘quit’ command to exit

Parameters:: prompt_text (str) – Text to display in the prompt
Returns:: Validated Path to the input file
Raises:: SystemExit – If user types ‘quit’
Return type:: pathlib.Path

Example

>>> print_section("INPUT FILE SELECTION")
>>> input_path = prompt_input_file()

build_tools.tui_common.interactive.print_extraction_complete(syllables_path, metadata_path, output_base_dir)[source]

Print extraction completion message with output paths.

Parameters:

syllables_path (pathlib.Path) – Path to saved syllables file
metadata_path (pathlib.Path) – Path to saved metadata file
output_base_dir (pathlib.Path) – Base output directory for relative path display

Example

>>> print_extraction_complete(
...     syllables_path=Path("output/20260110/syllables/test.txt"),
...     metadata_path=Path("output/20260110/meta/test.txt"),
...     output_base_dir=Path("output/"),
... )