firecrown.fctools.common
========================

.. py:module:: firecrown.fctools.common

.. autoapi-nested-parse::

   Common utility functions for fctools.

   This module provides shared functionality used across multiple fctools,
   including JSON loading, module importing, and standardized error handling.



Functions
---------

.. autoapisummary::

   firecrown.fctools.common.load_json_file
   firecrown.fctools.common.import_class_from_path
   firecrown.fctools.common.import_module_from_file
   firecrown.fctools.common.cli_error
   firecrown.fctools.common.cli_warning
   firecrown.fctools.common.validate_input_file
   firecrown.fctools.common.validate_output_path
   firecrown.fctools.common.format_line_ranges


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

.. py:function:: load_json_file(console, file_path, error_context = 'reading file')

   Load JSON file with standard error handling.

   :param console: The rich console object.
   :param file_path: Path to the JSON file to load
   :param error_context: Context description for error messages
   :return: The loaded JSON data as a dictionary
   :raises SystemExit: If the file cannot be read or parsed (exits with code 1)

   .. note::
       This function will exit the program on error rather than raising exceptions,
       as it's designed for CLI tools that should fail gracefully.


.. py:function:: import_class_from_path(console, full_path)

   Import a class or type from a fully qualified module path.

   :param console: The rich console object.
   :param full_path: Fully qualified path to the class (e.g., 'mymodule.MyClass')
   :return: The imported class/type object
   :raises SystemExit: If the module or class cannot be imported (exits with code 1)

   Example usage::

       >>> cls = import_class_from_path('pathlib.Path')
       >>> isinstance(cls, type)
       True


.. py:function:: import_module_from_file(console, file_path, module_name = 'temp_module')

   Import a Python module from a file path.

   This is useful for dynamically loading modules for inspection without
   requiring them to be on the Python path.

   :param console: The rich console object.
   :param file_path: Path to the Python file to import
   :param module_name: Name to give the imported module (default: 'temp_module')
   :return: The imported module object
   :raises SystemExit: If the module cannot be imported (exits with code 1)

   .. note::
       This function executes the module code, so use with caution on untrusted files.


.. py:function:: cli_error(console, message, exit_code = 1)

   Print error message to stderr and exit the program.

   :param console: The rich console object (unused, kept for API consistency).
   :param message: Error message to display
   :param exit_code: Exit code (default: 1)

   .. note::
       This function never returns; it always exits the program.


.. py:function:: cli_warning(console, message)

   Print warning message to stderr without exiting.

   :param console: The rich console object (unused, kept for API consistency).
   :param message: Warning message to display


.. py:function:: validate_input_file(console, file_path, file_description = 'Input file')

   Validate that an input file exists and is readable.

   :param console: The rich console object.
   :param file_path: Path to the file to validate
   :param file_description: Description of the file for error messages
   :raises SystemExit: If the file doesn't exist or isn't readable (exits with code 1)


.. py:function:: validate_output_path(console, output_path, overwrite = False)

   Validate output path and check overwrite permissions.

   :param console: The rich console object.
   :param output_path: Path where output will be written
   :param overwrite: Whether overwriting existing files is allowed
   :raises SystemExit: If the file exists and overwrite is False (exits with code 1)


.. py:function:: format_line_ranges(lines)

   Group consecutive line numbers into readable ranges.

   :param lines: List of line numbers
   :return: List of formatted strings representing line ranges

   Example usage::

       >>> format_line_ranges([1, 2, 3, 5, 6, 8])
       ['1-3', '5-6', '8']
       >>> format_line_ranges([10])
       ['10']
       >>> format_line_ranges([])
       []