firecrown.fctools.common

Common utility functions for fctools.

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

Functions

load_json_file(console, file_path[, error_context])	Load JSON file with standard error handling.
import_class_from_path(console, full_path)	Import a class or type from a fully qualified module path.
import_module_from_file(console, file_path[, module_name])	Import a Python module from a file path.
cli_error(console, message[, exit_code])	Print error message to stderr and exit the program.
cli_warning(console, message)	Print warning message to stderr without exiting.
validate_input_file(console, file_path[, file_description])	Validate that an input file exists and is readable.
validate_output_path(console, output_path[, overwrite])	Validate output path and check overwrite permissions.
format_line_ranges(lines)	Group consecutive line numbers into readable ranges.

Module Contents

firecrown.fctools.common.load_json_file(console, file_path, error_context='reading file')

Load JSON file with standard error handling.

Parameters:

• console (rich.console.Console) – The rich console object.

• file_path (pathlib.Path) – Path to the JSON file to load

• error_context (str) – Context description for error messages

Returns:

The loaded JSON data as a dictionary

Raises:

SystemExit – If the file cannot be read or parsed (exits with code 1)

Return type:

dict[str, Any]

Note

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

firecrown.fctools.common.import_class_from_path(console, full_path)

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

Parameters:

• console (rich.console.Console) – The rich console object.

• full_path (str) – Fully qualified path to the class (e.g., ‘mymodule.MyClass’)

Returns:

The imported class/type object

Raises:

SystemExit – If the module or class cannot be imported (exits with code 1)

Return type:

type[Any]

Example usage:

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

firecrown.fctools.common.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.

Parameters:

• console (rich.console.Console) – The rich console object.

• file_path (pathlib.Path) – Path to the Python file to import

• module_name (str) – Name to give the imported module (default: ‘temp_module’)

Returns:

The imported module object

Raises:

SystemExit – If the module cannot be imported (exits with code 1)

Return type:

Any

Note

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

firecrown.fctools.common.cli_error(console, message, exit_code=1)

Print error message to stderr and exit the program.

Parameters:

• console (rich.console.Console) – The rich console object (unused, kept for API consistency).

• message (str) – Error message to display

• exit_code (int) – Exit code (default: 1)

Return type:

None

Note

This function never returns; it always exits the program.

firecrown.fctools.common.cli_warning(console, message)

Print warning message to stderr without exiting.

Parameters:

• console (rich.console.Console) – The rich console object (unused, kept for API consistency).

• message (str) – Warning message to display

Return type:

None

firecrown.fctools.common.validate_input_file(console, file_path, file_description='Input file')

Validate that an input file exists and is readable.

Parameters:

• console (rich.console.Console) – The rich console object.

• file_path (pathlib.Path) – Path to the file to validate

• file_description (str) – Description of the file for error messages

Raises:

SystemExit – If the file doesn’t exist or isn’t readable (exits with code 1)

Return type:

None

firecrown.fctools.common.validate_output_path(console, output_path, overwrite=False)

Validate output path and check overwrite permissions.

Parameters:

• console (rich.console.Console) – The rich console object.

• output_path (pathlib.Path) – Path where output will be written

• overwrite (bool) – Whether overwriting existing files is allowed

Raises:

SystemExit – If the file exists and overwrite is False (exits with code 1)

Return type:

None

firecrown.fctools.common.format_line_ranges(lines)

Group consecutive line numbers into readable ranges.

Parameters:

lines (list[int]) – List of line numbers

Returns:

List of formatted strings representing line ranges

Return type:

list[str]

Example usage:

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