build_tools.name_selector.cli
=============================

.. py:module:: build_tools.name_selector.cli

.. autoapi-nested-parse::

   Command-line interface for the name selector.

   This module provides the CLI for filtering and ranking name candidates
   against a name class policy. It follows the project's CLI documentation
   standards with sphinx-argparse compatible argument parser.

   Usage
   -----
   Select first names from 2-syllable candidates::

       python -m build_tools.name_selector \
           --run-dir _working/output/20260110_115453_pyphen/ \
           --candidates candidates/pyphen_candidates_2syl.json \
           --name-class first_name \
           --count 100

   Use soft mode (penalties instead of hard rejection)::

       python -m build_tools.name_selector \
           --run-dir _working/output/20260110_115453_pyphen/ \
           --candidates candidates/pyphen_candidates_2syl.json \
           --name-class first_name \
           --mode soft



Functions
---------

.. autoapisummary::

   build_tools.name_selector.cli.create_argument_parser
   build_tools.name_selector.cli.parse_arguments
   build_tools.name_selector.cli.extract_extractor_type
   build_tools.name_selector.cli.resolve_candidates_path
   build_tools.name_selector.cli.extract_prefix_and_syllables
   build_tools.name_selector.cli.main


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

.. py:function:: create_argument_parser()

   Create and return the argument parser for the name selector.

   Returns
   -------
   argparse.ArgumentParser
       Configured ArgumentParser ready to parse command-line arguments.

   Notes
   -----
   This function follows the project's CLI documentation standards,
   enabling sphinx-argparse to auto-generate documentation.


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

   Parse command-line arguments.

   Parameters
   ----------
   args : list[str] | None, optional
       Arguments to parse. If None, uses sys.argv.

   Returns
   -------
   argparse.Namespace
       Parsed arguments.


.. py:function:: extract_extractor_type(run_dir)

   Extract extractor type from run directory name.

   Parameters
   ----------
   run_dir : Path
       Run directory like "_working/output/20260118_201318_pyphen"

   Returns
   -------
   str | None
       Extractor type (e.g., "pyphen", "nltk") or None if not found.


.. py:function:: resolve_candidates_path(run_dir, candidates)

   Resolve candidates path, auto-detecting prefix if needed.

   If the specified path doesn't exist, tries to find a matching file
   using the extractor type from the run directory name.

   Parameters
   ----------
   run_dir : Path
       Run directory path
   candidates : Path
       Candidates path (relative to run_dir)

   Returns
   -------
   Path
       Resolved candidates path (may be different from input if auto-detected)


.. py:function:: extract_prefix_and_syllables(candidates_filename)

   Extract prefix and syllable count from candidates filename.

   Parameters
   ----------
   candidates_filename : str
       Filename like "pyphen_candidates_2syl.json"

   Returns
   -------
   tuple[str, int]
       (prefix, syllable_count) e.g., ("pyphen", 2)

   Raises
   ------
   ValueError
       If filename doesn't match expected pattern.


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

   Main entry point for the name selector CLI.

   Parameters
   ----------
   args : list[str] | None, optional
       Command-line arguments. If None, uses sys.argv.

   Returns
   -------
   int
       Exit code (0 for success, non-zero for error).