build_tools.tui_common.cli_utils

Shared CLI utilities for build tools.

This module provides common functionality used across multiple CLI tools, including tab completion, file discovery, and corpus database integration.

These utilities were extracted from the syllable extractor CLIs to eliminate duplication and ensure consistent behavior across tools.

Attributes

`READLINE_AVAILABLE`
`CORPUS_DB_AVAILABLE`

Functions

`record_corpus_db_safe`(operation, func[, quiet])	Execute corpus_db operation with safe error handling.
`path_completer`(text, state)	Tab completion function for file paths.
`setup_tab_completion`()	Configure readline for tab completion with file paths.
`input_with_completion`(prompt)	Get user input with tab completion enabled.
`discover_files`(source[, pattern, recursive])	Discover text files in a directory matching the specified pattern.

Module Contents

build_tools.tui_common.cli_utils.READLINE_AVAILABLE = True

build_tools.tui_common.cli_utils.CORPUS_DB_AVAILABLE = True

build_tools.tui_common.cli_utils.record_corpus_db_safe(operation, func, quiet=False)[source]

Execute corpus_db operation with safe error handling.

If corpus_db recording fails, logs warning to stderr but allows extraction to continue. Ensures corpus_db is purely observational.

Parameters:

operation (str) – Description of operation (e.g., “start run”)
func (collections.abc.Callable[[], Any]) – Callable performing the corpus_db operation
quiet (bool) – If True, suppress warning messages

Returns:

Result of func() if successful, None if failed

Return type:

Any

build_tools.tui_common.cli_utils.path_completer(text, state)[source]

Tab completion function for file paths.

This enables bash-like tab completion for navigating directories and selecting files.

Parameters:

text (str) – The current text being completed
state (int) – The completion state (0 for first call, incremented for each match)

Returns:

The next completion match, or None when no more matches

Return type:

str | None

build_tools.tui_common.cli_utils.setup_tab_completion()[source]

Configure readline for tab completion with file paths.

This enables: - Tab completion for file and directory names - Tilde (~) expansion for home directory - Standard bash-like completion behavior

build_tools.tui_common.cli_utils.input_with_completion(prompt)[source]

Get user input with tab completion enabled.

Parameters:: prompt (str) – The prompt to display
Returns:: User input string
Return type:: str

build_tools.tui_common.cli_utils.discover_files(source, pattern='*.txt', recursive=False)[source]

Discover text files in a directory matching the specified pattern.

This function searches for files matching a glob pattern in the specified directory, optionally recursing into subdirectories. Results are sorted alphabetically for deterministic processing order.

Parameters:

source (pathlib.Path) – Directory to search for files. Must be an existing directory.
pattern (str) – Glob pattern for file matching (default: “.txt”). Examples: “.txt”, “.md”, “data_.csv”
recursive (bool) – If True, search recursively into subdirectories using rglob. If False, search only the top level (default: False).

Returns:

List of Path objects for matching files, sorted alphabetically. Returns empty list if no files match.

Raises:

ValueError – If source is not a directory or doesn’t exist.

Return type:

list[pathlib.Path]

Example

>>> # Find all .txt files in a directory
>>> files = discover_files(Path("/data/texts"))
>>> print(f"Found {len(files)} files")

>>> # Find all .md files recursively
>>> files = discover_files(Path("/data"), pattern="*.md", recursive=True)

>>> # Find files with custom pattern
>>> files = discover_files(Path("/data"), pattern="book_*.txt")