build_tools.nltk_syllable_extractor.file_io
===========================================

.. py:module:: build_tools.nltk_syllable_extractor.file_io

.. autoapi-nested-parse::

   File I/O operations for NLTK-based syllable extraction.

   This module handles all file reading, writing, and output generation
   for the NLTK syllable extractor.



Attributes
----------

.. autoapisummary::

   build_tools.nltk_syllable_extractor.file_io.DEFAULT_OUTPUT_DIR


Functions
---------

.. autoapisummary::

   build_tools.nltk_syllable_extractor.file_io.generate_output_filename
   build_tools.nltk_syllable_extractor.file_io.save_metadata


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

.. py:data:: DEFAULT_OUTPUT_DIR

.. py:function:: generate_output_filename(output_dir = None, language_code = None, run_timestamp = None, input_filename = None)

   Generate output filenames in run-based subdirectory structure.

   Creates a run directory with timestamp and 'nltk' identifier, then organizes
   outputs into syllables/ and meta/ subdirectories:
   - output_dir/YYYYMMDD_HHMMSS_nltk/syllables/filename.txt
   - output_dir/YYYYMMDD_HHMMSS_nltk/meta/filename.txt

   This structure groups each extraction run's outputs together, making it
   easier to manage, archive, or delete complete runs as atomic units.

   :param output_dir: Base output directory. Defaults to _working/output/
   :param language_code: Optional language code (e.g., 'en_US').
                         Used for filename if input_filename not provided.
   :param run_timestamp: Optional timestamp string (YYYYMMDD_HHMMSS format).
                         If provided, uses this timestamp for the run directory name.
                         If not provided, generates a new timestamp using datetime.now().
                         **Critical for batch processing** - pass the same timestamp to group
                         all files from a batch into one run directory.
   :param input_filename: Optional input filename to use for output naming.
                          If provided, output files will use this name (e.g., 'alice.txt').
                          Takes precedence over language_code for naming.

   :returns: Tuple of (syllables_path, metadata_path)

   .. admonition:: Example

      >>> # Interactive mode - single file with language code
      >>> syllables_path, meta_path = generate_output_filename(language_code='en_US')
      >>> print(syllables_path)
      _working/output/20260110_153022_nltk/syllables/en_US.txt
      
      >>> # Batch mode - multiple files sharing one run directory
      >>> timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
      >>> s1, m1 = generate_output_filename(
      ...     run_timestamp=timestamp,
      ...     input_filename='alice.txt'
      ... )
      >>> s2, m2 = generate_output_filename(
      ...     run_timestamp=timestamp,
      ...     input_filename='middlemarch.txt'
      ... )
      >>> print(s1)
      _working/output/20260110_153022_nltk/syllables/alice.txt
      >>> print(s2)
      _working/output/20260110_153022_nltk/syllables/middlemarch.txt
      >>> # Both files share the same run directory

   .. note::

      For batch processing, always pass the same run_timestamp to group all
      outputs into a single run directory. This represents one logical batch
      operation, regardless of how many input files are processed.


.. py:function:: save_metadata(result, output_path)

   Save extraction metadata to a text file.

   :param result: ExtractionResult containing metadata to save
   :param output_path: Path to the output metadata file

   :raises IOError: If there's an error writing the file

   .. admonition:: Example

      >>> result = ExtractionResult(...)
      >>> save_metadata(result, Path("output.meta.txt"))