build_tools.syllable_walk.cli

Command-line interface for syllable walker.

This module provides both interactive and batch processing functionality for exploring syllable feature space through random walks.

Usage:

python -m build_tools.syllable_walk [options]

Examples:

# Generate a single walk
python -m build_tools.syllable_walk data.json --start ka --profile dialect

# Compare all profiles
python -m build_tools.syllable_walk data.json --start bak --compare-profiles

# Generate batch of walks
python -m build_tools.syllable_walk data.json --batch 50 --output walks.json

For interactive web interface, use the separate syllable_walk_web module:

python -m build_tools.syllable_walk_web

Functions

create_argument_parser()

Create and return the argument parser for syllable walker.

parse_arguments([args])

Parse command-line arguments.

single_walk_mode(walker, args)

Handle single walk generation mode.

compare_profiles_mode(walker, args)

Handle profile comparison mode.

batch_mode(walker, args)

Handle batch walk generation mode.

search_mode(walker, args)

Handle syllable search mode.

main([args])

Main entry point for syllable walker CLI.

Module Contents

build_tools.syllable_walk.cli.create_argument_parser()[source]

Create and return the argument parser for syllable walker.

This function creates the ArgumentParser with all CLI options but does not parse arguments. This separation allows Sphinx documentation tools to introspect the parser and auto-generate CLI documentation.

Returns:

Configured ArgumentParser ready to parse command-line arguments

Return type:

argparse.ArgumentParser

Examples

Create parser and inspect options:

>>> parser = create_argument_parser()
>>> parser.prog
'cli.py'

Use parser to parse arguments:

>>> parser = create_argument_parser()
>>> args = parser.parse_args(["data.json", "--start", "ka"])
>>> args.start
'ka'

Notes

  • This function is used by both the CLI and documentation generation

  • For normal CLI usage, use main() which calls this internally

  • Sphinx-argparse can introspect this function to generate docs

build_tools.syllable_walk.cli.parse_arguments(args=None)[source]

Parse command-line arguments.

Parameters:

args (list[str] | None) – List of argument strings to parse. If None, uses sys.argv[1:]. This parameter is useful for testing.

Returns:

Parsed arguments as argparse.Namespace object

Return type:

argparse.Namespace

Example

>>> args = parse_arguments(["data.json", "--start", "ka"])
>>> args.start
'ka'
build_tools.syllable_walk.cli.single_walk_mode(walker, args)[source]

Handle single walk generation mode.

Parameters:
Returns:

Exit code (0 = success, 1 = error)

Return type:

int

build_tools.syllable_walk.cli.compare_profiles_mode(walker, args)[source]

Handle profile comparison mode.

Parameters:
Returns:

Exit code (0 = success, 1 = error)

Return type:

int

build_tools.syllable_walk.cli.batch_mode(walker, args)[source]

Handle batch walk generation mode.

Parameters:
Returns:

Exit code (0 = success, 1 = error)

Return type:

int

build_tools.syllable_walk.cli.search_mode(walker, args)[source]

Handle syllable search mode.

Parameters:
Returns:

Exit code (0 = success)

Return type:

int

build_tools.syllable_walk.cli.main(args=None)[source]

Main entry point for syllable walker CLI.

Parses arguments, validates inputs, initializes walker, and executes requested operation mode.

Parameters:

args (list[str] | None) – Command-line arguments. If None, uses sys.argv.

Returns:

  • 0: Success

  • 1: Error (file not found, invalid arguments, etc.)

  • 2: Validation error (incompatible arguments)

  • 130: Keyboard interrupt (Ctrl+C)

Return type:

Exit code

Notes

  • Errors are printed to stderr

  • Normal output goes to stdout

  • Keyboard interrupt (Ctrl+C) exits cleanly with code 130