build_tools.pyphen_syllable_normaliser.cli
==========================================

.. py:module:: build_tools.pyphen_syllable_normaliser.cli

.. autoapi-nested-parse::

   Command-line interface for syllable normalization pipeline.

   This module provides the main CLI entry point for the syllable_normaliser tool,
   which processes pyphen extractor output with 3-step normalization pipeline.



Functions
---------

.. autoapisummary::

   build_tools.pyphen_syllable_normaliser.cli.detect_pyphen_run_directories
   build_tools.pyphen_syllable_normaliser.cli.run_full_pipeline
   build_tools.pyphen_syllable_normaliser.cli.create_argument_parser
   build_tools.pyphen_syllable_normaliser.cli.parse_arguments
   build_tools.pyphen_syllable_normaliser.cli.main


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

.. py:function:: detect_pyphen_run_directories(source_dir)

   Detect pyphen run directories within source directory.

   Searches for directories matching the pattern YYYYMMDD_HHMMSS_pyphen/
   which contain a syllables/ subdirectory.

   :param source_dir: Directory to search for pyphen run directories.

   :returns: List of Path objects pointing to pyphen run directories,
             sorted by directory name (chronological order).

   .. admonition:: Example

      >>> source = Path("_working/output/")
      >>> runs = detect_pyphen_run_directories(source)
      >>> for run in runs:
      ...     print(run.name)
      20260110_143022_pyphen
      20260110_153045_pyphen


.. py:function:: run_full_pipeline(run_directory, config, verbose = False, quiet = False)

   Run complete pyphen normalization pipeline with in-place processing.

   Executes the full pyphen-specific workflow:
   1. Aggregate syllables from run_directory/syllables/*.txt
   2. Canonicalize syllables (Unicode normalization, etc.)
   3. Frequency analysis
   4. Write 5 output files to run_directory (in-place)

   :param run_directory: Pyphen run directory (e.g., _working/output/20260110_143022_pyphen/).
   :param config: NormalizationConfig specifying normalization parameters.
   :param verbose: If True, print detailed progress information.
   :param quiet: If True, suppress all output except errors.

   :returns: NormalizationResult containing all outputs, statistics, and file paths.

   :raises FileNotFoundError: If run_directory or syllables/ subdirectory doesn't exist.
   :raises ValueError: If run_directory is not a directory.

   .. admonition:: Example

      >>> from pathlib import Path
      >>> config = NormalizationConfig(min_length=2, max_length=8)
      >>> run_dir = Path("_working/output/20260110_143022_pyphen/")
      >>> result = run_full_pipeline(
      ...     run_directory=run_dir,
      ...     config=config,
      ...     verbose=True
      ... )
      >>> result.stats.raw_count
      15234
      >>> result.stats.unique_canonical
      4821


.. py:function:: create_argument_parser()

   Create and return the argument parser for pyphen syllable normaliser.

   :returns: Configured ArgumentParser ready to parse command-line arguments.


.. py:function:: parse_arguments(args = None)

   Parse command-line arguments.


.. py:function:: main(argv = None)

   Main entry point for CLI.

   :param argv: Command-line arguments (for testing). If None, uses sys.argv.

   :returns: Exit code (0 for success, 1 for error).