build_tools.pipeline_tui.services.validators
============================================

.. py:module:: build_tools.pipeline_tui.services.validators

.. autoapi-nested-parse::

   Directory validators for Pipeline TUI browsers.

   This module provides validation functions for the DirectoryBrowserScreen
   that check whether directories are suitable for source input or output.

   **Validator Function Signature:**

   All validators return a tuple of ``(is_valid, type_label, message)``:

   - ``is_valid``: True if directory can be selected
   - ``type_label``: Short label describing valid directories (e.g., "source")
   - ``message``: Error message if invalid, or description if valid

   **Example Usage:**

   .. code-block:: python

       from build_tools.tui_common.controls import DirectoryBrowserScreen
       from build_tools.pipeline_tui.services.validators import validate_source_directory

       result = await app.push_screen_wait(
           DirectoryBrowserScreen(
               title="Select Source",
               validator=validate_source_directory,
           )
       )



Functions
---------

.. autoapisummary::

   build_tools.pipeline_tui.services.validators.validate_source_directory
   build_tools.pipeline_tui.services.validators.validate_output_directory
   build_tools.pipeline_tui.services.validators.validate_corpus_directory


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

.. py:function:: validate_source_directory(path)

   Validate a directory as a source for text extraction.

   A valid source directory contains at least one ``.txt`` file,
   either directly or in subdirectories.

   :param path: Directory path to validate

   :returns:

             - is_valid: True if directory contains extractable files
             - type_label: "source" if valid
             - message: File count if valid, error description if invalid
   :rtype: Tuple of (is_valid, type_label, message)


.. py:function:: validate_output_directory(path)

   Validate a directory as an output location for pipeline results.

   Any existing directory is valid. Non-existent paths are invalid
   (the pipeline will create timestamped subdirectories, but the
   parent must exist).

   :param path: Directory path to validate

   :returns:

             - is_valid: True if directory exists and is writable
             - type_label: "output" if valid
             - message: Status description
   :rtype: Tuple of (is_valid, type_label, message)


.. py:function:: validate_corpus_directory(path)

   Validate a directory as a processed corpus (for syllable_walk_tui compatibility).

   A valid corpus directory contains either NLTK or pyphen normalized output:

   - NLTK corpus: ``nltk_syllables_unique.txt`` and ``nltk_syllables_frequencies.json``
   - Pyphen corpus: ``pyphen_syllables_unique.txt`` and ``pyphen_syllables_frequencies.json``

   This function is provided for compatibility with syllable_walk_tui,
   which needs to select processed corpus directories.

   :param path: Directory path to validate

   :returns:

             - is_valid: True if directory contains valid corpus files
             - corpus_type: "nltk" or "pyphen" if valid, empty if invalid
             - message: Corpus info if valid, error description if invalid
   :rtype: Tuple of (is_valid, corpus_type, message)