build_tools.tui_common.ledger
=============================

.. py:module:: build_tools.tui_common.ledger

.. autoapi-nested-parse::

   Shared corpus database ledger helpers for extraction tools.

   This module provides a context manager and helper functions for integrating
   with the corpus database ledger. The ledger is observational only - it records
   what happened but does not influence extraction behavior.

   These utilities eliminate duplicated corpus DB integration patterns across
   the pyphen and NLTK syllable extractors.

   Usage::

       from build_tools.tui_common.ledger import ExtractionLedgerContext

       with ExtractionLedgerContext(
           extractor_tool="pyphen_syllable_extractor",
           extractor_version="0.5.0",
           min_len=2,
           max_len=8,
           quiet=False,
       ) as ctx:
           # Record inputs
           ctx.record_input(input_path)

           # ... do extraction ...

           # Record outputs
           ctx.record_output(
               output_path=syllables_path,
               unique_syllable_count=len(syllables),
               meta_path=metadata_path,
           )

           # Mark success or failure
           ctx.set_result(success=True)



Classes
-------

.. autoapisummary::

   build_tools.tui_common.ledger.ExtractionLedgerContext


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

.. py:class:: ExtractionLedgerContext(extractor_tool, extractor_version = 'unknown', pyphen_lang = None, min_len = None, max_len = None, recursive = False, pattern = None, command_line = None, quiet = False)

   Context manager for corpus database ledger integration.

   Handles the full lifecycle of ledger operations:
   - Initialize ledger on entry
   - Start run with extraction parameters
   - Record inputs and outputs during extraction
   - Complete run with success/failure status on exit
   - Close ledger connection

   All operations are safe - failures are logged but don't block extraction.

   .. attribute:: extractor_tool

      Name of the extraction tool

   .. attribute:: extractor_version

      Version string of the tool

   .. attribute:: pyphen_lang

      Language code for pyphen (None for NLTK)

   .. attribute:: min_len

      Minimum syllable length constraint

   .. attribute:: max_len

      Maximum syllable length constraint

   .. attribute:: recursive

      Whether directory scanning was recursive

   .. attribute:: pattern

      File pattern for directory scanning

   .. attribute:: command_line

      Full command-line invocation

   .. attribute:: quiet

      Suppress warning messages

   .. admonition:: Example

      >>> with ExtractionLedgerContext(
      ...     extractor_tool="pyphen_syllable_extractor",
      ...     extractor_version="0.5.0",
      ...     pyphen_lang="en_US",
      ...     min_len=2,
      ...     max_len=8,
      ... ) as ctx:
      ...     ctx.record_input(Path("input.txt"))
      ...     # ... extraction ...
      ...     ctx.record_output(syllables_path, len(syllables), metadata_path)
      ...     ctx.set_result(success=True)

   Initialize the ledger context.

   :param extractor_tool: Name of the extraction tool
   :param extractor_version: Version string of the tool
   :param pyphen_lang: Language code for pyphen (None for NLTK or auto-detect)
   :param min_len: Minimum syllable length constraint
   :param max_len: Maximum syllable length constraint
   :param recursive: Whether directory scanning was recursive
   :param pattern: File pattern for directory scanning
   :param command_line: Full command-line invocation (defaults to sys.argv)
   :param quiet: Suppress warning messages


   .. py:attribute:: extractor_tool


   .. py:attribute:: extractor_version
      :value: 'unknown'



   .. py:attribute:: pyphen_lang
      :value: None



   .. py:attribute:: min_len
      :value: None



   .. py:attribute:: max_len
      :value: None



   .. py:attribute:: recursive
      :value: False



   .. py:attribute:: pattern
      :value: None



   .. py:attribute:: command_line
      :value: ''



   .. py:attribute:: quiet
      :value: False



   .. py:property:: is_available
      :type: bool


      Check if corpus DB integration is available and initialized.


   .. py:property:: run_id
      :type: int | None


      Get the current run ID, or None if not initialized.


   .. py:method:: set_result(success)

      Explicitly set the extraction result.

      Call this before exiting the context to indicate success or failure.
      If not called, success is assumed unless an exception occurs.

      :param success: True if extraction succeeded, False if failed



   .. py:method:: record_input(source_path, file_count = None)

      Record an input source for this run.

      :param source_path: Path to input file or directory
      :param file_count: Number of files if source_path is a directory



   .. py:method:: record_inputs(files, source_dir = None)

      Record multiple input files for this run.

      If source_dir is provided, records the directory with file count.
      Otherwise, records each file individually.

      :param files: List of input file paths
      :param source_dir: Source directory (if files were discovered from a directory)



   .. py:method:: record_output(output_path, unique_syllable_count = None, meta_path = None)

      Record an output file for this run.

      :param output_path: Path to generated syllables file
      :param unique_syllable_count: Number of unique syllables extracted
      :param meta_path: Path to corresponding metadata file