build_tools.tui_common.batch
============================

.. py:module:: build_tools.tui_common.batch

.. autoapi-nested-parse::

   Shared batch processing utilities for syllable extractors.

   This module provides common batch processing orchestration that can be used
   by both pyphen and NLTK syllable extractors. It abstracts the common patterns
   of processing multiple files while allowing extractor-specific logic.

   Usage::

       from build_tools.tui_common.batch import run_batch_extraction

       # Define extractor-specific single-file processor
       def process_file(input_path, output_dir, run_timestamp, verbose):
           # ... extraction logic ...
           return FileProcessingResult(...)

       # Run batch with shared orchestration
       result = run_batch_extraction(
           files=files_to_process,
           output_dir=output_dir,
           process_file_func=process_file,
           extractor_name="pyphen",
           language_display="en_US",
           min_len=2,
           max_len=8,
           quiet=False,
           verbose=True,
       )



Attributes
----------

.. autoapisummary::

   build_tools.tui_common.batch.SingleFileProcessor


Functions
---------

.. autoapisummary::

   build_tools.tui_common.batch.run_batch_extraction
   build_tools.tui_common.batch.collect_files_from_args
   build_tools.tui_common.batch.validate_extraction_params


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

.. py:data:: SingleFileProcessor

.. py:function:: run_batch_extraction(files, output_dir, process_file_func, batch_result_class, extractor_name, language_display, min_len, max_len, quiet = False, verbose = False)

   Run batch extraction with shared orchestration logic.

   This function provides the common batch processing pattern:
   - Generate shared timestamp for the batch run
   - Create output directory
   - Display batch header
   - Process each file with progress indicators
   - Collect and return results

   :param files: List of input file paths to process
   :param output_dir: Output directory for all results
   :param process_file_func: Callable that processes a single file.
                             Signature: (input_path, output_dir, run_timestamp, verbose) -> FileProcessingResult
   :param batch_result_class: Class to use for BatchResult (from models module)
   :param extractor_name: Name of extractor for display ("pyphen" or "nltk")
   :param language_display: Language string for display (e.g., "en_US", "auto")
   :param min_len: Minimum syllable length (for display)
   :param max_len: Maximum syllable length (for display)
   :param quiet: Suppress all output except errors
   :param verbose: Show detailed progress for each file

   :returns: BatchResult with overall statistics and individual file results.

   .. admonition:: Example

      >>> from build_tools.pyphen_syllable_extractor.models import BatchResult
      >>>
      >>> def my_processor(path, out_dir, timestamp, verbose):
      ...     # Process file and return FileProcessingResult
      ...     pass
      >>>
      >>> result = run_batch_extraction(
      ...     files=[Path("a.txt"), Path("b.txt")],
      ...     output_dir=Path("output/"),
      ...     process_file_func=my_processor,
      ...     batch_result_class=BatchResult,
      ...     extractor_name="pyphen",
      ...     language_display="en_US",
      ...     min_len=2,
      ...     max_len=8,
      ... )


.. py:function:: collect_files_from_args(file_arg, files_arg, source_arg, pattern, recursive)

   Collect files to process from CLI arguments.

   Validates and resolves paths from the three mutually exclusive input modes:
   - Single file (--file)
   - Multiple files (--files)
   - Directory scan (--source)

   :param file_arg: Single file path (from --file)
   :param files_arg: List of file paths (from --files)
   :param source_arg: Directory path (from --source)
   :param pattern: File pattern for directory scanning
   :param recursive: Whether to scan directories recursively

   :returns: Tuple of (list of resolved file paths, source directory or None)

   :raises ValueError: If validation fails (file not found, not a file, etc.)
   :raises SystemExit: If no input is specified

   .. admonition:: Example

      >>> files, source_dir = collect_files_from_args(
      ...     file_arg=Path("input.txt"),
      ...     files_arg=None,
      ...     source_arg=None,
      ...     pattern="*.txt",
      ...     recursive=False,
      ... )


.. py:function:: validate_extraction_params(min_len, max_len)

   Validate extraction parameters.

   :param min_len: Minimum syllable length
   :param max_len: Maximum syllable length

   :raises SystemExit: If validation fails